Download Reports with Archive in BeyondTrust Remote Support

Download Reports with Archive

The Archive query returns a gzip compressed file with the system state or an event log for a given date and time. The file must be decompressed before it can be parsed. The decompressed file never exceeds 4 GB. History is stored for the past seven active days (days that the B Series Appliance's processes have been running).

State archives are created automatically every thirty minutes, and event archives contain events spanning an interval of ten minutes. Each archive corresponds with an archive listing. Integrations must choose the appropriate archive and replay events from that archive to reconstruct the state at a given point in time.

Archives are not available immediately after the time they represent. It may take a few minutes for a state or event archive to be created. It is helpful to query ArchiveListing before querying Archive to be sure that the archive has been created.

The reporting API is an authenticated API. For instructions on using authenticated APIs using OAuth, see Authenticate to the Remote Support API. The API account must have the permission Allow Access to Archive Reports.

To run ArchiveListing or Archive reports, ensure that the Enable Archive API option is checked on the Management > API Configuration page of the /login administrative interface. The state archive API can be enabled independently of other APIs.

Parameters for Archive

type=[string]	The type of archive to download. May be either state or event.
date=[YYYY-MM-DD]	Specifies the date for which to return the archive.
index=[integer]	The index of the archive to download. This index corresponds with the index in ArchiveListing.

JSON Response for Archive Query

The state archive file consists of a single JSON (JavaScript Object Notation) object. Multiple tables and IDs may be specified. If a table does not have any data, its value is null. Possible tables and fields are detailed below.

The event archive file consists of a JSON object for each line in the decompressed file. Events are ordered from oldest to newest in the order in which they actually occurred. Possible tables and fields are detailed below. The following event types are supported:

model_insert	Creates a table with all fields included, even if blank.
model_update	Adds or modifies one or more rows in a table.
model_delete	Removes a table.
truncate_model	Signifies that the B Series Appliance's processes have restarted and that all events logged so far are no longer valid. If any integrations are building data or tables based on the event archive file, they should clean all rows from all tables when this event is received.
session_event	Creates a table with data about events that occurred within the session.

JSON Tables and Fields for model_insert and model_update

customer_client

Stores all customer clients connected to the B Series Appliance. Note that a support_session can exist without a customer_client. This typically occurs when the customer closes the customer client and the representative does not immediately terminate the session in the representative console.

(id)	An integer that identifies this table row. This ID is unique for the lifetime of the model.
"client_type":"[string]"	The type of customer client running on the endpoint or communicating with the endpoint. May be one of desktop, mobile, rdp, vnc, vpro, shell, or web_chat.
"connected":[boolean]	1: The customer client is connected to the B Series Appliance. 0: The customer client is not connected. The endpoint system may be rebooting or in the process of elevating.
"created_timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this table row was created.
"elevated":[boolean]	1: The customer client is running in an elevated context. 0: The customer client is running in a user context.
"hostname":"[string]"	The endpoint's hostname.
"operating_system":"[string]"	The endpoint's operating system.
"private_ip":"[string]"	The endpoint's private IP address.
"public_ip":"[string]"	The endpoint's public IP address.
"support_session_id":[integer]	The foreign key that links this table row to other table rows that reference this session.

queue

Stores all active support session queues. A queue is active if one or more of its members are logged in or if it is a persistent queue.

(id)	An integer that identifies this table row. This ID is unique for the lifetime of the model.
"code_name":"[string]"	The code name assigned to the support team. Personal queues do not have code names.
"created_timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this table row was created.
"name":"[string]"	The support team's display name.
"support_team_id":"[string]"	The support team's unique identifier. The ID is not shown for personal queues.
"type":"[string]"	The type of queue. May be one of prewait, team, or personal.

representative

Stores all representatives logged into a representative console

(id)	An integer that identifies this table row. This ID is unique for the lifetime of the model.
"connected":[boolean]	1: The representative is connected to the B Series Appliance. 0: The representative is not connected to the B Series Appliance. A representative may be considered logged in even if the representative console is not connected to the B Series Appliance. This could occur if the representative console has lost its connection but the reconnect timeout has not been reached.
"console_in_focus":[boolean]	1: The representative console is in focus on the representative's computer. 0: The representative console is not in focus.
"created_timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this table row was created.
"hostname":"[string]"	The hostname of the representative's system.
"operating_system":"[string]"	The operating system of the representative's system.
"private_display_name":"[string]"	The representative's private display name.
"private_ip":"[string]"	The private IP address of the representative's system.
"public_display_name":"[string]"	The representative's public display name.
"public_ip":"[string]"	The public IP address of the representative's system.
"queue_id":[integer]	The unique ID serving as the foreign key that links this table row with other table rows that reference this queue.
"routing_available":[boolean]	1: The representative is available to handle new support sessions. 0: The representative is unavailable to handle new support sessions.
"routing_busy":[boolean]	1: The representative has reached their maximum number of support sessions for session assignment. 0: The representative is not marked as busy.
"routing_enabled":[boolean]	1: The representative has automatic session assignment enabled. 0: The representative has automatic session assignment disabled.
"routing_idle":[boolean]	1: The representative is idle. 0: The representative is active.
"selected_support_session_id":[integer]	The ID of the support session currently active in the representative console. The active support session is recorded once every five seconds. If the representative switches sessions very frequently, some of those session selection change events may not be recorded.
"skill_code_names":"[string]"	A comma-separated list of skill code names assigned to this representative.
"type":"[string]"	The type of representative connection. May be one of normal or invited.
"user_id":[integer]	The representative's unique ID which identifies them in BeyondTrust.
"username":"[string]"	The username this representative uses to authenticate to BeyondTrust.

representative_queue

Stores logged-in representatives in relation to their support queues. While team leads and managers have access to their team members' personal queues, that access is not represented in this table.

(id)	An integer that identifies this table row. This ID is unique for the lifetime of the model.
"created_timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this table row was created.
"queue_id":[integer]	The unique ID serving as the foreign key that links this table row with other table rows that reference this queue.
"representative_id":[integer]	The unique ID serving as the foreign key that links this table row with other table rows that reference this representative.
"role":[string]	The user's role in the team. May be one of member, lead, or manager.

representative_support_session

Stores representatives participating in support sessions.

(id)	An integer that identifies this table row. This ID is unique for the lifetime of the model.
"created_timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this table row was created.
"representative_id":[integer]	The unique ID serving as the foreign key that links this table row with other table rows that reference this representative.
"selected_support_session_service_tool":"[string]"	The selected support session service tab. May be one of screen_sharing, file_transfer, system_information, remote_shell, or registry.
"support_session_id":[integer]	The foreign key that links this table row to other table rows that reference this session.

representative_support_session_tool

Stores a list of support tools in use by representatives in sessions. Rows are added when the representative starts using the tool and are removed when the representative stops using the tool.

(id)	An integer that identifies this table row. This ID is unique for the lifetime of the model.
"created_timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this table row was created.
"representative_id":[integer]	The unique ID serving as the foreign key that links this table row with other table rows that reference this representative.
"support_session_id":[integer]	The foreign key that links this table row to other table rows that reference this session.
"tool":"[string]"	The selected support session service tab. May be one of screen_sharing, file_transfer, system_information, remote_shell, or registry.

support_session

Stores all active support sessions.

(id)	An integer that identifies this table row. This ID is unique for the lifetime of the model.
"created_timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this table row was created.
"customer_company":"[string]"	The end user's company name.
"customer_company_code":"[string]"	The end user's company code.
"customer_description":"[string]"	The issue description as provided by the customer.
"customer_name":"[string]"	The end user's name.
"estimated_pickup_timestamp":[timestamp]	The time at which the system expects this session to be accepted or transferred. This could be a time in the past or future.
"issue_code_name":"[string]"	The code name of the issue selected by the customer on the front-end survey.
"issue_description":"[string]"	The description of the issue selected by the customer on the front-end survey.
"lsid":"[string]"	The logging session ID that uniquely identifies this session. This LSID can be used in /login > Reports, with the reporting API, in the integration client, etc.
"primary_team_queue_id":[integer]	The unique ID serving as the foreign key that links this table row with other table rows that reference this queue. This field stores the last team queue that owned the session before the session ended.
"priority":[integer]	The session's priority. May be one of 1 (high), 2 (medium), or 3 (low).
"public_site_id":[integer]	The ID of the public site associated with the session.
"public_site_name":"[string]"	The name of the public site associated with the session.
"queue_entry_timestamp":[timestamp]	The time at which this session entered its current queue.
"queue_id":[integer]	The unique ID serving as the foreign key that links this table row with other table rows that reference this queue. This field stores the queue in which the session currently resides.
"start_method":"[string]"	The method with which the session was started. May be one of session_key (the seven-digit code or the URL), rep_list, issue_submission, , local_jump, remote_jump, shell_jump, local_rdp, remote_rdp, local_vnc, remote_vnc, or vpro.

support_session_attribute

Stores custom session attributes assigned to active support sessions.

(id)	An integer that identifies this table row. This ID is unique for the lifetime of the model.
"code_name":"[string]"	The code name assigned to the support session attribute.
"created_timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this table row was created.
"support_session_id":[integer]	The foreign key that links this table row to other table rows that reference this session.
"value":"[string]"	The value of the attribute.

support_session_skill

Stores skills assigned to active support sessions.

(id)	An integer that identifies this table row. This ID is unique for the lifetime of the model.
"code_name":"[string]"	The code name assigned to the skill.
"created_timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this table row was created.
"support_session_id":[integer]	The foreign key that links this table row to other table rows that reference this session.

presentation_session

Stores data about the presentation sessions.

(id)	An integer that identifies this table row. This ID is unique for the lifetime of the model.
"created_timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this table row was created.
"lsid":[guid]	The logging session ID that uniquely identifies this session. This LSID can be used on /login > Reports and in the Reporting API, among other places.
"presentation_name":"[string]"	The name of the presentation.

attendee

Stores all information about attendees who have joined a presentation.

"connected":[boolean]	1: The presentation client connected to the B Series Appliance and joined the presentation. 0: The presentation client did not connect to the B Series Appliance.
"created_timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this table row was created.
"hostname":"[string]"	The attendee's hostname.
"name":"[string]"	The name of the attendee.
"operating_system":"[string]"	The attendee's operating system.
"presentation_session_id":[integer]	The logging session ID that uniquely identifies this presentation.
"private_ip":"[string]"	The attendee computer's private IP address.
"public_ip":"[string]"	The attendee computer's public IP address.
(id)	An integer that identifies this table row. This ID is unique for the lifetime of the model.

presenter

Stores the information about the presenter who has started presenting their screen.

(id)	An integer that identifies this table row. This ID is unique for the lifetime of the model.
"created_timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this table row was created.
"presentation_session_id":[integer]	The logging session ID that uniquely identifies this presentation.
"representative_id":[integer]	The unique ID serving as the foreign key that links this table row with other table rows that reference this representative.

JSON Tables and Fields for session_event

These data elements are returned for session events. All but the data element occur for each session event.

"data":[object]	Contains details about the session event. These details are described in the tables below.
"lsid":"[string]"	The logging session ID that uniquely identifies this session. This LSID can be used in /login > Reports, with the reporting API, in the integration client, etc.
"name":"[string]"	The name of the session event. These session events are described in the tables below.
"timestamp":[timestamp]	A UNIX timestamp (UTC) representing the time at which this event occurred.
"type":"[string]"	The type of table. The value is fixed to session_event for all session events.

callback_button_deployed

"callback_button_id":[integer]	The ID of the Support Button that was deployed.
"description":"[string]"	The description of the Support Button as entered by the representative.
"expiration":[timestamp]	A UNIX timestamp (UTC) representing the time at which the Support Button will expire.
"profile_id":[integer]	The ID of the Support Button profile used.
"profile_name":"[string]"	The name of the Support Button profile used.
"representative_id":[integer]	The unique ID of the representative who deployed the Support Button.

callback_button_removed

"callback_button_id":[integer]	The ID of the Support Button that was removed.
"representative_id":[integer]	The unique ID of the representative who removed the Support Button.

canned_script_executed

"script_name":"[string]"

The name of the canned script that was executed.

chat_message

"body":"[string]"	The message to be rendered in the recipient's chat window. The body can contain the %name% macro. Integrations should substitute it with the name of the performed_by member.
"destination":[object]	The list of recipients receiving the chat message.
"performed_by":[object]	The list of the name-value pairs showing who performed the chat operation.

command_shell_session_started

"download_url":"[string]"	The URL to download the command shell recording.
"instance":[integer]	The index of the command shell instance.
"representative_id":[integer]	The unique ID of the representative who started the command shell operation.
"view_url":"[string]"	The URL to view the command shell recording.

customer_exit_survey

"responses":[object]

The list of question-answer pairs in the customer exit survey.

directory_created

"destination":[object]	The list of name-value pairs showing on which member's system the directory was created.
"failure_reason":"[string]"	Optional: The reason the directory creation failed, shown only if an error occurred.
"path":"[string]"	The absolute path of the directory.
"performed_by":[object]	The list of name-value pairs showing who created the directory.

file_deleted

"destination":[object]	The list of name-value pairs showing from which member's system the file was deleted.
"failure_reason":"[string]"	Optional: The reason the file deletion failed, shown only if an error occurred.
"name":"[string]"	The name of the deleted file.
"performed_by":[object]	The list of name-value pairs showing who deleted the file.
"size":[integer]	The size of the deleted file, given in bytes.

file_download

"destination":[object]	The list of name-value pairs showing to which member's system the file was downloaded.
"name":"[string]"	The name of the downloaded file.
"performed_by":[object]	The list of name-value pairs showing from which member's system the file was downloaded.
"size":[integer]	The size of the downloaded file, given in bytes.

file_download_incomplete

"bytes_transferred":[integer]	The number of bytes transferred successfully before the file download failed.
"destination":[object]	The list of name-value pairs showing to which member's system the file was being downloaded.
"failure_reason":"[string]"	The reason the file download failed.
"name":"[string]"	The name of the file being downloaded.
"performed_by":[object]	The list of name-value pairs showing from which member's system the file was being downloaded.

file_moved

"destination":[object]	The list of name-value pairs showing on which member's system the file was moved.
"failure_reason":"[string]"	Optional: The reason the move failed, shown only if an error occurred.
"new_path":"[string]"	The absolute path of the file after it was moved.
"old_path":"[string]"	The absolute path of the file before it was moved.
"performed_by":[object]	The list of name-value pairs showing who moved the file.

file_upload

"destination":[object]	The list of name-value pairs showing to which member's system the file was uploaded.
"name":"[string]"	The name of the uploaded file.
"performed_by":[object]	The list of name-value pairs showing from which member's system the file was uploaded.
"size":[integer]	The size of the uploaded file, given in bytes.

file_upload_incomplete

"bytes_transferred":[integer]	The number of bytes transferred successfully before the file upload failed.
"destination":[object]	The list of name-value pairs showing to which member's system the file was being uploaded.
"failure_reason":"[string]"	The reason the file upload failed.
"name":"[string]"	The name of the file being uploaded.
"performed_by":[object]	The list of name-value pairs showing from which member's system the file was being uploaded.

files_shared

"files":[object]

The list of shared files and their attributes. This object contains the following elements:

<name> The name of the shared file.

<size> The size of the shared file.

<type> The file type. Possible values of this field are file and dir.

"performed_by":[object]

The list of name-value pairs showing which member shared the files.

legal_agreement_response

"response":"[string]"	The action taken by the end-user. Possible values are accept, decline, and timeout.
"text":"[string]"	The text of the legal agreement shown in the message box to the customer.
"title":"[string]"	The title of the message box where the legal agreement was shown to the customer.

registry_exported

"representative_id":[integer]	The unique ID of the representative who exported the registry.
"root_path":"[string]"	The root of the exported tree.

registry_imported

"representative_id":[integer]

The unique ID of the representative who imported the registry.

registry_key_added

"key":"[string]"	The name of the added registry key.
"path":"[string]"	The registry key's parent path.
"representative_id":[integer]	The unique ID of the representative who added the registry key.

registry_key_deleted

"key":"[string]"	The name of the deleted registry key.
"path":"[string]"	The registry key's parent path.
"representative_id":[integer]	The unique ID of the representative who deleted the registry key.

registry_key_renamed

"new_key":"[string]"	The registry key's name after modification.
"old_key":"[string]"	The registry key's name before modification.
"path":"[string]"	The registry key's parent path.
"representative_id":[integer]	The unique ID of the representative who renamed the registry key.

registry_value_added

"data":"[string]"	The data of the added registry key value.
"name":"[string]"	The name of the added registry key value.
"path":"[string]"	The key path to the added registry key value.
"representative_id":[integer]	The unique ID of the representative who added the registry key value.
"type":"[string]"	The type of the added registry key value data.

registry_value_deleted

"name":"[string]"	The data of the deleted registry key value.
"path":"[string]"	The key path to the deleted registry key value.
"representative_id":[integer]	The unique ID of the representative who deleted the registry key value.

registry_value_modified

"name":"[string]"	The name of the modified registry key value.
"new_data":"[string]"	The data of the registry key value after modification.
"old_data":"[string]"	The data of the registry key value before modification.
"path":"[string]"	The key path to the modified registry key value.
"representative_id":[integer]	The unique ID of the representative who modified the registry key value.
"type":"[string]"	The type of the modified registry key value data.

registry_value_renamed

"new_name":"[string]"	The name of the registry key value after modification.
"old_name":"[string]"	The name of the registry key value before modification.
"path":"[string]"	The key path to the registry key value.
"representative_id":[integer]	The unique ID of the representative who renamed the registry key value.

representative_survey

"responses":[object]

The list of question-answer pairs in the representative survey.

screen_recording

"download_url":"[string]"	The URL to download the screen recording.
"representative_id":[integer]	The unique ID of the representative in session during this recording.
"view_url":"[string]"	The URL to view the screen recording.

screenshot_captured

"representative_id":[integer]

The unique ID of the representative who captured this screenshot.

session_assigned

"representative_id":[integer]	The unique ID of the representative who received the session assignment alert.
"timeout":[integer]	Optional: The number of seconds before the alert timed out if it was not accepted.

session_assignment_response

"response":"[string]"

Text representing the response to the session assignment request.

session_foreground_window_changed

"exe_name":"[string]"	The executable name of the foreground window.
"window_name":[string]"	The title of the foreground window.

session_note_added

"body":"[string]"	The message to be rendered as a session note.
"number":[integer]	The index of the session note that was created for this session.
"representative_id":[integer]	The unique ID of the representative who added the session note.

show_my_screen_recording

"download_url":"[string]"	The URL to download the show my screen recording.
"instance":[integer]	The index of the show my screen recording instance.
"representative_id":[integer]	The unique ID of the representative showing their screen.
"view_url":"[string]"	The URL to view the show my screen recording.

special_action_executed

"action_name":"[string]"

The name of the special action that was executed.

system_information_retrieved

"system_information":[object]

This object contains multiple data sets, each with a category name, a columns element with a list of field names for the category, and a rows element with field values for each field name.

JSON Tables and Fields for Presentation Session Events

The Presentation Session Event shows the events that are logged into the event archive file.

The following session events are excluded from the archive file: Session Start, Session End, Conference Member Added, Conference Member Removed, and Conference Member State Changed. These are excluded because the data needed to log these events can be created from existing state model tables like presentation_session, presenter, and attendee. Please see System State Model of the Real-Time API for more information.

Required Data Elements

Chat Message

"performed_by":[object]	The list of the name-value pairs showing who performed the chat operation.
"destination":[object]	The list of the recipients who will be receiving the chat message.
"body":"[string]"	Message to be rendered in the recipient's chat window. The body can contain the %name macro. The integrations should substitute it with the name of the performed_by member.

Files Shared

"performed_by":[object]	The list of the name-value pairs showing who shared the files.
"files":"[object]"	The list of the shared files and their attributes. This object contains following elements: <name> is the name of the file. <size> is the size of the file. <type> is the file type. valid values of this field are file and dir.

Screen Recording

"presenter_id":[integer]	The unique ID of the presenter.
"download_url":"[string]"	The URL to download the screen recording.
"view_url":[integer]	The URL to view the screen recording.
"appliance_guid":"[string]"	The GUID of the B Series Appliance where the recording was created.

Use Cases

Integrations can use the available data to generate metrics as needed. Below are some examples of how certain metrics could be generated from the data.

Average Work Time

The average amount of time a representative spends actively working on a single support session. Work time for a single session includes all time where the following are true:

The representative console has focus (representative.console_in_focus = true)
The support session is selected (representative.selected_support_session_id = support_session.id)
The customer client is connected (customer_client.connected = true)
The representative is not idle (representative.routing_idle = false)

The average work time can be computed for a set of sessions over a given time range. For example, compute the average work time for all sessions between 8am and 5pm on a given date.

Total Active Time

The cumulative amount of time the representative was responsible for an active support session. Active time for a single session includes all time where the following are true:

The support session is in the representative's personal queue (representative.id = queue.representative_id AND queue.id = support_session.queue_id)
The representative is in the support session (representative_support_session.support_session_id = support_session.id AND representative_support_session.representative_id = representative_id)
The customer client is connected (customer_client.connected = true)

The total active time is the sum of active time for all sessions over a given time range.

Rep Login/out Time

When a representative logs in, a new row is inserted into the representative table.

When a representative logs out, a row is removed from the representative table.

The representative.connected field can be used to know when a representative is logged in but not connected.

Number of Users Logged In during a Given Period of Time

Count the number of rows in the representative table. The period of time can be replayed using the event archive to compute the minimum, maximum, and average number of representatives logged in.