Representative Console Scripting and Client Scripting API

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

  1. The Bomgar Representative Console Script file format
  2. New and deprecated command line parameters for the representative 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 representative 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 representative console will use the OS to associate the representative console with the BRCS file type. Therefore users can double-click a BRCS file and have it automatically executed by the Bomgar representative 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 representative console from external applications.

Customers can use the client scripting API to generate BRCS 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".

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. Most commands have required and/or optional parameters. Available actions include:

login start_rdp_session
generate_session_key start_shell_jump_session
push_and_start_local start_vpro_session
push_and_start_remote start_vnc_session
start_pinned_client_session delete_script_file

Two actions are automatically added to the BRCS file: login and delete_script_file. The delete_script_file action has no parameters.