Start Sessions with External Keys (TicketID)

The external key is a text string sent to the B Series Appliance to be logged as a property of a particular support session. This key typically originates from software separate from the BeyondTrust software. It does not need to be a unique value but usually is. The external key can be specified in one of two ways.

Manual Entry

The support representative who has ownership of a BeyondTrust session can manually assign a key value from within the representative console. The summary pane of a session displays that session’s external key. Click the Edit External Key button to modify this value. You can edit the external key from either the Session Info tab or the Custom Info tab. Editing the external key in one location will change it in both.

Programmatic Assignment

The second, more useful way of designating an external key is from within the URL sent to the B Series Appliance by the customer client. The external key can be specified with any of the session start methods documented above, as well as with the generate_session_key command detailed below.

The issue submission survey generates an HTTP request similar in format to the following example:

https://support.example.com/api/start_session?issue_menu=1&customer.name=John%20Doe&customer.company=Company%20Name&customer.company_code=1234&customer.details=I%20need%20support&id=1&session.custom.external_key=1234

Note the session.custom.external_key parameter specified in the sample request provided. If an external key is specified in this manner, the representative console will automatically populate its external key field with the given value.

The API allows creation of a custom web site or application that can be used instead of the public site to establish a support session. Code within this custom software must generate HTTP requests in the format displayed in the example above to initiate the session and pre-populate the external key within the representative console.

Using the External Key

Once a support session has an external key associated with it, you can use the reporting API to generate XML session data containing the external key. This provides the means for middleware to be developed to provide a relationship between the reporting data used by BeyondTrust and the correlating ticketing system’s ticket numbers.