Editorial Note: In September 2018, privileged access management (PAM) provider Bomgar acquired BeyondTrust and now operates under this name. We’ve since updated this article text to reflect that change.

BEYONDTRUST API

You can access the BeyondTrust API documentation here.

BASIC CONFIGURATION

There are three main steps required to configure everything in Vivantio:

1. Create a Custom Form to hold the BeyondTrust Session Details
2. Create an Email Template to send the session details to customer
3. Create the Webhook to allows the technician to create the session

CUSTOM FORM

Why do you need a Custom Form?

The “Generate Session” method in the BeyondTrust API gives us back a number of different values and we will need these to be available in Vivantio.

The main value we need is the “key_url” field, but you can also set up fields for:

• Expiry Date
• Queue
• Short Key
• Key URL

Begin by logging into Vivantio and going to the Admin Area. You will then go to:

System Areas » Incidents » Custom Forms

From there, you can start adding fields:

(Note: All of the field can be created as “Read only” fields as they will be populated by the Webhook and not end users.)

Having created the fields: create a Custom Form with those fields on the following screen:

EMAIL TEMPLATE

In order to create the Email Template, navigate to:

Admin » System Areas » Incidents » Templates » External Emails

From there, you can click the “Add” button and enter the email you would like to be sent to your end user. You can see our example below:

After saving the email, make sure that the template is available for the “Add Note” process by using the “Action Types” button on the email template list.

WEBHOOK

In order to create the Webook, navigate to:

Admin » Integration & API » Webhooks

From there, you can click the “Add Webhook” button. You will then choose “Incident” and see the Add Webhook screen. You can name this what you like, but, for our example, we will name it “Start BeyondTrust Session”. From there, you will need to fill out a number of tabbed parameters. You can see an example of what that will look like below:

Notes on Specific Fields:

Basic Details » Request URL:

This is the format it should be in:

https://instance.beyondtrust.com/api/command?username=username&password=password&action=generate_session_key&type=support&queue_id=general

The bolded and italicized values should be specific to your BeyondTrust account. You might also want to change the “type” and “queue_id” values to match your instance.

Response Fields:

This tab allows us to extract information from the BeyondTrust response and put it in a Custom Form. We recommend using XPath to get the values out. Here’s an example of what that would look like in practice:

USING THE WEBHOOK

Having completed all of these steps, you should be able to see the “Start BeyondTrust Session” link on the Ticket Details page such as in the example below:

When selecting that option, an email should be sent to your customer, complete with a link to join the BeyondTrust session.