Representative Console Scripting and Client Scripting API

The Bomgar Representative Console scripting feature is composed of three parts:

  1. The Bomgar Rep Console Script file format
  2. New and deprecated command line parameters for the rep console
  3. The Bomgar client scripting API

The Bomgar Representative Console Script File

A Bomgar Representative Console Script (BRCS) is a file that contains a sequence of commands to be executed by the Bomgar Rep Console. The file extension is in the format "brcs-<companySiteName>" (Company Site Name is the name used to access your support site). During installation the Bomgar Rep Console will use the OS to associate the rep console with the BRCS file type. Therefore users can double-click a BRCS file and have it automatically executed by the Bomgar Rep Console.

BRCS files have the following format:

BRCS1.0

<command>

<command>

This is more formally expressed as:

brcs_file = header , newline , commands ;

header = "BRCS" , version ;

version = digit , "." , digit ;

commands = command { newline , command } ;

digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

newline = "\n" | "\r\n" ;

Note that script files can have a maximum of 10 commands.

Each command consists of a set of key-value pairs separated by ”&”. The key in each pair is separated from the value by ”=”. Keys and values use the percent-encoding algorithm described in RFC3986 section 2.1. This is commonly referred to as url-encoding or url-escaping. It is commonly seen in the address bar of web browsers to represent the parameters passed to a web server. Commands have the following format:

action=<action>&parameter1=value1&parameter2=value2...

This is more formally expressed as:

command = "action=", value, [ parameters ] ;

parameters = "&", parameter, [ parameters ] ;

parameter = url_encoded_string, "=", url_encoded_string ;

url_encoded_string = {* see RFC 3986 *} ;

New and Deprecated Command Line Parameters for the Representative Console

Two command line parameters have been added to the representative console to support BRCS:

run-script <BRCS command>

run-script-file <path to BRCS file>

These command line parameters allow customers to implement BRCS login via the command line. These two new parameters overlap with two existing parameters. Therefore, the "-jump" and "-push" command line parameters are now deprecated and will be removed in a future release.

Example
Old Command Line New Command Line
push<hostname> run-script "action=push_and_start_local&hostname=<hostname>"
jump<search string> run-script "action=start_pinned_client_session&search_string=<search_string>"

Different behaviors can be seen when running a script from the command line depending on the state of the representative console:

  • If the representative console is not running, then attempting to run a script from the command line causes the representative console to start the login dialog. After the representative successfully logs in, the script is run.
  • If the representative console is already running, but the representative is not logged in, then the login dialog is shown. After the representative logs in, the script is run.
  • If the representative console is already running and the representative is already logged in, then attempting to run a script from the command line causes the existing instance of the representative console to run the script.

Representative console exit status:

  • If an invalid script is given on the command line, then the representative console will terminate with an exit status > 0.
  • If a valid script is given on the command line, then the representative console will terminate with an exit status of 0.

Examples:

bomgar-rep-x64.exe --run-script "action=generate_session_key&session.custom.external_key=123456789"

bomgar-rep-x64.exe --run-script-file my_script_file.brcs-beta60

The Bomgar Client Scripting API

The client scripting API enables you to generate a Bomgar Representative Console Scripting (BRCS) file which allows you to send commands to the Bomgar Rep Console from external applications. The client scripting API was introduced in API version 1.6.0 and BRCS functionality was introduced in 11.1.

Customers can use the client scripting API to generate BCRS files that can start a support session with a specific Jump Client, push and start a session with a Windows system within a local network, prompt representatives to generate a session key, start a vPro session with a specified system, or to simply log into the representative console.

The client scripting API URL is https://support.example.com/api/client_script.

This API accepts a client type (rep), an operation to perform (generate), a command to put in the script file, and a set of parameters to pass to the command. Here is an example of a valid Client Scripting API request:

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_pinned_client_session&search_string=ABCDEFG02

The above request will prompt the user to download a Bomgar representative console script file. After downloading the script file, the user can run it using the representative console. In this case, the script file will contain commands to start a session with the Jump Client whose hostname, comments, public IP, or private IP matches the search string "ABCDEFG02".

Note: By default, access to the API is SSL-encrypted; however, you can choose to allow HTTP access by checking the Allow HTTP Access to XML API option on the Management > API Configuration page of the /login administrative interface. It is highly recommended that HTTP remain disallowed as a security best practice.

Required Parameters for Client Scripting API
type=rep The Bomgar client to which the command applies. Currently the API only supports rep as the client type.
operation=generate

The operation to perform. Currently the API only supports generate as the operation.

action=<command>

or

action=<command>&parameter=[value]

The name of the command to run.

Beginning with API version 1.7.1 and Bomgar 12.1.4, two actions are automatically added to the BRCS file: login and delete_script_file. See below for the full list of available commands.

Parameters and Values Available for action=<command>
action=start_pinned_client_session&

search_string=[string]

session.custom.external_key =[string]

action=start_vpro_session&

target=[string]

jumpoint=[strinstarting]

session.custom.external_key=[string] (optional)

Note: To initiate a vPro session using Bomgar Client Scripting, you must specify the target machine's hostname or private IP. (If Kerberos is used for vPro authentication, then the FQDN must be specified.) The Jumpoint name must also be specified. An example is as follows: action=start_vpro_session&target=mycomputer&Jumpoint=My%Jumpoint

action=generate_session_key&

session.custom.external_key=[string]

public_portal_hostname=[string]

Note: Parameters are optional for the generate_session_key command. Omitting them will simply cause the representative console to show the Generate Session Key dialog.

action=push_and_start_local&

hostname=[string]

session.custom.external_key=[string]

action=login&

mechanism=username_password "currently only username_password is supported"

username=[string]

myusername&mypassword=[string]

Note: Command attempts to use last saved credentials. Command has no effect if the representative console is already logged in. This must be the first command in a script file. Only one login command is appropriate per BRCS file. This command will pass the login mechanism and, optionally, a username and password. If no options are specified command will simply launch the rep console and attempt to login with any save credentials. The mechanism parameter currently only supports username_password as its argument. The username and password parameters are required, only if mechanism == username_password. Both username and password parameters are sent in plain text, unencrypted.

action=delete_script_file This command has no parameters