Download Reports with SupportSession
The SupportSession query returns full information for all sessions which match given search parameters. You may use any of the following sets of parameters to generate reports:
- start_date and duration
- start_time and duration
- end_date and duration
- end_time and duration
- lsid
- lsids
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 Support Session Reports and Recordings.
Parameters for SupportSession
| start_date=[YYYY-MM-DD] | Specifies that the report should return all sessions, even those still in progress, that began on or after this date and that are within the duration specified below. |
| start_time=[timestamp] | Specifies that the report should return all sessions, even those still in progress, that began at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC). |
| end_date=[YYYY-MM-DD] | Specifies that the report should return only closed sessions that ended on or after this date and that are within the duration specified below. |
| end_time=[timestamp] | Specifies that the report should return only closed sessions that ended at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC). |
| duration=[integer] | Length of time from the specified date or time for which you wish to pull reports, or 0 to pull from the specified date to present. If start_date or end_date is specified, duration will represent days; if start_time or end_time is specified, duration will represent seconds. |
| lsid=[string] | The ID of the session for which you wish to see details. |
| lsids=[comma-separated strings] | A comma-delimited list of the IDs of sessions for which you wish to see details. |
Optional Parameter for SupportSession
| limit=[string] |
The category by which to filter results. Can be one of the following:
The limit parameter cannot be used in conjunction with either lsid or lsids. If it is used with either of these parameters, the limit parameter will be ignored. |
XML Response for SupportSession Query
| <session_list> | Contains a <session> element for each session that matches the given criteria. If no sessions are returned, this element will contain no <session> elements. If an error occurs during the search, it will contain an <error> element describing the problem. |
Element Names and Attributes
| lsid (attribute) | A string which uniquely identifies this session. |
| <session_type> | Indicates the type of session for which the report was run. The value will always be support in the current BeyondTrust API version. |
| <lseq> |
An incrementing number used to represent support sessions in a non-string format. The LSEQ element is not guaranteed to be unique or strictly sequential. |
| <start_time> | The date and time the session was begun either by the customer’s running the customer client or by the representative’s initiating a Jump session. Data is returned in ISO 8601 format. Also contains a timestamp attribute which displays the start time as a UNIX timestamp (UTC). |
| <end_time> | The date and time the session was ended either by the customer’s closing the customer client or by the representative’s closing the session. Data is returned in ISO 8601 format. Also contains a timestamp attribute which displays the end time in UNIX timestamp (UTC). This element will be empty for sessions which are still in progress when the report was run or which closed abnormally. |
| <duration> | Session length in HH:MM:SS format. |
| <public_site> | The name of the public site associated with the session. Also contains an id attribute, which displays the unique ID assigned to the public site. |
| <jumpoint> | The name of the Jumpoint through which this session was initiated, if any. Also contains an id attribute, which displays the unique ID assigned to the Jumpoint. |
| <external_key> | An arbitrary string that can link this session to an identifier on an external system, such as a help desk ticket ID. This can be input from within the representative console or defined programmatically. |
| <custom_attributes> | Contains a <custom_attribute> element for each custom field assigned to a session. This element displays only if custom fields have been defined. The format of each <custom_attribute> element is described below. |
| <session_chat_view_url> | The URL at which this session’s chat transcript can be viewed in a web browser. This element is displayed only for sessions that have successfully ended. |
| <session_chat_download_url> | The URL at which this session’s chat transcript can be downloaded. This element is displayed only for sessions that have successfully ended. |
| <session_recording_view_url> | The URL at which the video of the session may be viewed in a web browser. This element is displayed only if screen sharing recording was enabled at the time of the session. It is available only for sessions that have successfully ended and only if the requesting user has permission to view session recordings. |
| <session_recording_download_url> | The URL at which the video of the session may be downloaded. This element is displayed only if screen sharing recording was enabled at the time of the session and only if the rep initiated screen sharing during the session. It is available only for sessions that have successfully ended and only if the requesting user has permission to view session recordings. |
| <show_my_screen_recordings> | Contains a <show_my_screen_recording> element for each Show My Screen session that was initiated during the session. This element is displayed only if the representative shared their screen during the session, if Show My Screen recording was enabled at the time of the session, and only if the requesting user has permission to view Show My Screen recordings. Each <show_my_screen_recording> element contains the child elements <download_url> and <view_url> as described below. |
| <command_shell_recordings> | Contains a <command_shell_recording> element for each command shell that was initiated during the session. This element is displayed only if the representative opened a remote command shell during the session, if command shell recording was enabled at the time of the session, and if the requesting user has permission to view session recordings. Each <command_shell_recording> element contains the child elements <download_url> and <view_url> as described below. |
| <file_transfer_count> | The number of file transfers which occurred during the session. |
| <file_move_count> | The number of files renamed via the File Transfer interface during the session. |
| <file_delete_count> | The number of files deleted via the File Transfer interface during the session. |
| <primary_customer> | Lists the gsnumber as an attribute and as an element the name of the customer who initiated the session or, for a Jump session, the computer name of the remote system accessed by the representative. |
| <primary_rep> | Lists the gsnumber and id as attributes, and as an element the name of the final representative to own the session. If the session closed before it was transferred to a representative, this element will not be displayed. |
| <primary_team> | Lists the team ID and name of the final team to which this session was transferred. If the session was never transferred to a team, this element will not be displayed. |
| <customer_list> | A list of all customers who participated in the session. There should always be exactly one customer per session in the current BeyondTrust API version. The format of each <customer> element is described below. |
| <rep_list> | A list of all representatives who participated in the session, whether as session owners or conference members. The format of each <representative> element is described below. If the customer closed the session before it was transferred to a representative, this element will be empty. |
| <team_list> | A list of all teams to which the session belonged, whether by the session being initiated in a team queue, by a representative’s explicitly transferring the session to a team, or by a session falling back into a team queue after a lost connection. This element may be empty, or it may contain one or more <team> elements as described below. |
| <cust_survey_list> | Contains a <cust_exit_survey> element if a customer exit survey was completed. This element is displayed only for sessions that have successfully ended and only if the customer submitted the survey. This element contains several child elements. |
| <rep_survey_list> | Contains a <rep_exit_survey> element if a representative survey was completed. This element is displayed only for sessions that have successfully ended and only if the representative submitted the survey. This element contains several child elements. |
| <session_details> |
Contains a chronological list of all events which occurred during the session. This element contains one or more child <event> elements. |
| display_name (attribute) | The display name assigned to the custom attribute. |
| code_name (attribute) | The code name assigned to the custom attribute. |
| instance (attribute) | The instance of the Show My Screen session, starting with 0. |
| <download_url> | The URL at which the video of the Show My Screen session may be downloaded. |
| <view_url> | The URL at which the video of the Show My Screen session may be viewed in a web browser. |
| instance (attribute) | The instance of the command shell session, starting with 0. |
| <download_url> | The URL at which the video of the command shell session may be downloaded. |
| <view_url> | The URL at which the video of the command shell session may be viewed in a web browser. |
| gsnumber (attribute) | Uniquely identifies the customer in regards to their current connection to the BeyondTrust Appliance B Series. A gsnumber may be recycled, so while two people connected at the same time will never have the same gsnumber, one person may have a gsnumber that was assigned to another person in the past. Can be used to correlate a <customer> element with a <primary_cust> or with an event’s <performed_by> or <destination> element. |
| <username> |
The name used to identify the customer during the session. The method used to obtain this name varies depending on how the session was started. |
| <public_ip> | The customer’s public IP address. |
| <private_ip> | The customer’s private IP address. |
| <hostname> | The hostname of the customer’s computer. |
| <os> | The operating system of the customer’s computer. |
| <primary_cust> | Integer value (1 or 0) indicating if this customer was the first customer of the session. In the current version of the BeyondTrust API, this value is always 1. |
| <info> | Contains detailed information about the customer as either entered in the front-end survey or designated programmatically. This field contains several child elements as described below. |
| <name> | The name which the customer entered in the Your Name field of the front-end survey or which was assigned programmatically. |
| <company> | The company name which the customer entered in the Company field on the front-end survey or which was assigned programmatically. |
| <company_code> | The code which the customer entered in the Company Code field on the front-end survey or which was assigned programmatically. |
| <issue> | The numeric ID of the issue or the representative which the customer selected from the dropdown of the front-end survey or which was designated programmatically. |
| <details> | The description of the problem as entered by the customer in the Describe Your Issue text area field of the front-end survey or as programmatically assigned. |
| gsnumber (attribute) |
Uniquely identifies the representative in regards to their current connection to the BeyondTrust Appliance B Series. A gsnumber is assigned on a per-connection basis, so if a representative leaves a session and then rejoins without logging out of the B Series Appliance, their gsnumber will remain the same. However, if the representative’s connection is terminated for any reason, when that representative logs back into the B Series Appliance, they will be assigned a new gsnumber and will also appear multiple times in the <rep_list> element. A gsnumber may be recycled, so while two people connected at the same time will never have the same gsnumber, one person may have a gsnumber that was assigned to another person in the past. Can be used to correlate a <representative> element with a <primary_rep> or with an event’s <performed_by> or <destination> element. |
| id (attribute) | Unique ID assigned to the representative. |
| <username> | The username assigned to the representative. |
| <display_name> | This element is deprecated as of API version 1.10.0 but still exists for backwards compatibility. Its value is the same as that of <private_display_name>. |
| <public_display_name> | The public display name assigned to the representative. Note that this field contains the public display name's value at the time of the conference, which may not match the current value if the public_display_name has subsequently been changed. |
| <private_display_name> | The private display name assigned to the representative. Note that this field contains the private display name's value at the time of the conference, which may not match the current value if the private_display_name has subsequently been changed. |
| <display_number> | The display number assigned to the representative. Like <display_name>, this is the display number at the time of the session and may not match the current value. |
| <public_ip> | The representative’s public IP address. |
| <private_ip> | The representative’s private IP address. |
| <hostname> | The hostname of the representative’s computer. |
| <os> | The operating system of the representative’s computer. |
| <session_owner> | Integer value (1 or 0) indicating whether the representative was an actual owner of the session or was merely a conference member. |
| <primary_rep> | Integer value (1 or 0) indicating if the representative was the final representative to own the session. |
| <seconds_involved> | Integer value indicating the number of seconds the representative was involved in this session. |
| <invited> |
Integer value (1) present only if the representative is an invited user. |
| [value] | The display name of the support team. Note that this field contains the team name as it currently appears, which may not match the value at the time of the session if the team name has been subsequently changed. |
| id (attribute) | Integer value representing the team’s unique ID. |
| primary_team (attribute) | Integer value (1 or 0) indicating if this team was the last team to which the session was transferred. |
| timestamp (attribute) | The system time at which the event occurred. | ||||||||||||||||||||||||||||||||||
| event_type (attribute) |
The type of event which occurred. Event types include the following:
*Will only appear if recording is enabled for this session. |
||||||||||||||||||||||||||||||||||
| <performed_by> | The entity that performed the action. Indicates the entity’s gsnumber and also its type, indicating whether this action was performed by the system, a customer, or a representative. | ||||||||||||||||||||||||||||||||||
| <destination> | The entity to which the event was directed. Indicates the entity’s gsnumber and also its type, indicating whether this action was directed to the system, a customer, or a representative. | ||||||||||||||||||||||||||||||||||
| <body> | The text of the message as displayed in the chat log area. | ||||||||||||||||||||||||||||||||||
| <encoded_body> | Can be shown in place of the <body> element above. Contains the base64 (RFC 2045 section 6.8) encoded value of what would have been shown in the <body> element, and is shown ONLY if the <body> text contains characters that are invalid according to XML specification. These characters are typically the result of binary data being sent through chat messages. | ||||||||||||||||||||||||||||||||||
| <filename> | The name of the transferred file. | ||||||||||||||||||||||||||||||||||
| <filesize> | An integer indicating the size of the transferred file. | ||||||||||||||||||||||||||||||||||
| <system_information> |
Applies only to System Information Retrieved events wherein the system information is pulled automatically upon session start. This element contains multiple <category> child elements as described below. System information is logged only when pulled automatically at the beginning of the session and not when specifically requested by the representative. This is to prevent overload with the large amount of dynamic data that can be retrieved from the remote system. |
||||||||||||||||||||||||||||||||||
| <files> | If this event involved the transferring of files, then this element will contain a <file> element for every file transferred. | ||||||||||||||||||||||||||||||||||
| <data> | Contains an arbitrary number of <value name="_" value="_" /> elements. The name and number of these elements varies based on event_type. For example, when a representative joins the session, a Conference Member Added event would contain <value> elements for the representative’s name, username, private_ip, public_ip, hostname, os, support_teams, and user_id. |
| <description> | Contains multiple <field> elements, each of which contains a descriptor for the specific data field. For example, the Drives category would have <field> elements Drive, Type, Percent Used, etc. These <field> elements can be compared to table header cells. |
| <data> | Contains multiple <row> elements, each of which contains multiple <field> elements that correspond to the <field> elements above. For example, the Drives category would have a separate <row> for each drive on the remote computer. An example <row> might contain <field> elements C:\, Local Disk, 60%, etc. These <row> elements can be compared to table rows, with each <field> element a table cell. |
Query Examples for SupportSession
| Sessions started October 1 2016 to present |
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2016-10-01&duration=0 |
| Sessions started the month of October 2016 |
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2016-10-01&duration=31 |
| Sessions started 8:00 AM October 1 2016 to present |
https://support.example.com/api/reporting?generate_report=SupportSession&start_time=1475308800&duration=0 |
| Sessions started 8:00 AM October 1 2016 to 6:00 PM October 1 2016 |
https://support.example.com/api/reporting?generate_report=SupportSession&start_time=1475308800&duration=36000 |
| Sessions ended October 1 2016 to present |
https://support.example.com/api/reporting?generate_report=SupportSession&end_date=2016-10-01&duration=0 |
| Sessions ended the month of October 2016 |
https://support.example.com/api/reporting?generate_report=SupportSession&end_date=2016-10-01&duration=31 |
| Sessions ended 8:00 AM October 1 2016 to 6:00 PM October 1 2016 |
https://support.example.com/api/reporting?generate_report=SupportSession&end_time=1475308800&duration=36000 |
| Session c69a8e10bea9428f816cfababe9815fe |
https://support.example.com/api/reporting?generate_report=SupportSession&lsid=c69a8e10bea9428f816cfababe9815fe |
| Sessions c69a8e10bea9428f816cfababe9815fe, a5eeaa58591047b88556f944804227b0, 5bf07601298b495b87310da9ce571e22 |
https://support.example.com/api/reporting?generate_report=SupportSession&lsids=c69a8e10bea9428f816cfababe9815fe,a5eeaa58591047b88556f944804227b0,5bf07601298b495b87310da9ce571e22 |
| Sessions started October 1 2016 to present for all sessions |
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2016-10-01&duration=0&limit=all |
| Sessions started October 1 2016 to present for a specific rep |
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2016-10-01&duration=0&limit=rep:1 |
| Sessions started October 1 2016 to present for all teams |
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2016-10-01&duration=0&limit=team:all |
| Sessions started October 1 2016 to present for a specific team |
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2016-10-01&duration=0&limit=team:1 |
| Sessions started October 1 2016 to present for members of a specific team |
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2016-10-01&duration=0&limit=members:1 |
| Sessions started October 1 2016 to present for a specific public site |
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2016-10-01&duration=0&limit=site:1 |
