Zendesk

⚠️

Important

You must purchase this integration separately for both your Remote Support software and your Zendesk solution. For more information, contact BeyondTrust's Sales team.

What is the Zendesk integration?

Service desks and customer support organizations using Zendesk can integrate with BeyondTrust to improve service levels, and central support processes, and strengthen compliance. This document describes the installation and configuration of the BeyondTrust Remote Support integration with Zendesk.

How is this integration useful?

The Zendesk integration with BeyondTrust Remote Support provides the following functionality:

• A BeyondTrust session key can be initiated from within a Zendesk ticket.
• An agent can type a machine name into a field on the screen and Jump to the device using BeyondTrust Jump Technology.
• A customer can request help on an existing issue via the Zendesk Customer Portal.
• The representative can manually associate a session with a particular Zendesk ticket by editing the external key while in a BeyondTrust session.
• A custom link in the BeyondTrust representative console can automatically open the ticket in Zendesk, once associated via the external key.
• When the BeyondTrust session ends, session data is pushed into Zendesk and can be viewed from within the ticket.

Important information about this integration

This integration consists of two main parts:

• Middleware, which receives event notifications from the B Series Appliance and pushes data into Zendesk.
• An app that can be installed within Zendesk to provide UI elements allowing the user to do things such as generate a session key or Jump to a remote system.

Prerequisites

To complete this integration, please ensure that you have the necessary software installed and configured as indicated in this guide, accounting for any network considerations.

Applicable versions

• BeyondTrust Remote Support: 14.x and newer
• Zendesk: "New" Zendesk (current platform since 9/12/2012)

Network considerations

The following network communication channels must be open for the integration to work properly:

Prerequisite installation and configuration

The Zendesk integration is a BeyondTrust Middleware Engine plugin.

ℹ️

Note

For more information on installing and working with the BeyondTrust Middleware Engine, see the Middleware Engine Guide.

Configure Zendesk

Download and install the BeyondTrust Remote Support app for Zendesk

1. Log in to the Zendesk Agent Interface as a user with Administrator access.
2. Click the Admin (gear) icon in the left navigation area to open the Admin Home menu.
3. Select Apps > Marketplace.
4. Search the Marketplace for BeyondTrust Remote Support.
5. Select and install the app.

Configure the app

1. Hostname (required) - The hostname of the BeyondTrust Appliance B Series.

2. Issues (required) - A list of issues from which an end-user can choose when using the Get Support Now button to start a chat session. These should be entered one per line with the format issue_code=IssueName, where issue_code is the code name configured for the issue in the BeyondTrust /login interface and IssueName is the user-friendly name displayed to the end-user in the dropdown.

   For example, if there is an issue in BeyondTrust named General Technical Issues with a code name of general_tech, the corresponding entry in the issues list in Zendesk should be general_tech=General Technical Issues.

3. Jumpoints - A list of Jumpoints configured for the B Series Appliance from which an agent can choose. These should be entered once per line.

4. Allow Jump-To Pinned Client Session - Determines if agents can Jump to Jump Clients.

5. Allow Push and Start Local Jump Session - Determines if agents can Jump to systems on their local network.

6. Allow Push and Start Remote Jump Session - Determines if agents can Jump to systems through a Jumpoint. If enabled, requires at least one Jumpoint to be entered.

7. Allow Remote Desktop (RDP) Session - Determines if agents can start Remote Desktop Protocol sessions through BeyondTrust. If enabled, requires at least one Jumpoint to be entered.

8. Allow Remote Console Session - Determines if agents can start Shell Jump sessions through BeyondTrust. If enabled, requires at least one Jumpoint to be entered.

Once the app is installed and configured, you can see the UI elements in the appropriate section when viewing an existing ticket.

ℹ️

Note

The integration functionality is not available until the ticket has been saved. Therefore, buttons are not present on a new, unsaved ticket, though the app does render a brief message to that effect.

Create a method for end-users to request support

1. When viewing a ticket as an administrator, click the Customize Help Center button.
2. This opens a modal with instructions for editing the current theme to add the Support button to ticket views for end-users. When clicked, a chat session starts and is automatically tied back to the ticket. The session is routed to the appropriate team based on the issue selected by the user before clicking the button.

ℹ️

Note

For information on configuring teams, issues, and session routing with BeyondTrust, see Support Teams, Issues, and Equilibrium for Automatic Session Routing.

Create a role and an agent account for REST API calls

1. Click the Admin (gear) icon in the left navigation area to open the Admin Home menu.
2. Under Manage > People, click Add Role.

ℹ️

Note

If your Zendesk plan does not support the creation of new roles, skip to step 4 and add the user to the Administrator role.

3. Create a role named API Only with the following permissions:

• Tickets > What kind of tickets can this agent access?: All
• Tickets > Can edit ticket properties?: Yes
• Tickets > Can edit ticket properties?: Yes
• Tickets > Can edit ticket tags?: Yes
• People > May this user view lists of user profiles?: Can view all users in your account
• Use defaults for all other permissions

4. Under Manage > People click Add User.
5. Create a new user named BeyondTrust API User (or whatever name you prefer) with the API Only role.
6. Verify the new API account via email.

Configure Remote Support

Several configuration changes are necessary on the B Series Appliance to integrate with Zendesk. You must make these changes on each B Series Appliance for which you intend to create a plugin configuration, described in the above Configure Zendesk section.

All of the steps in this section take place in the BeyondTrust /login administrative interface. Access your Remote Support interface by going to the hostname of your B Series Appliance followed by /login (e.g., https://support.example.com/login).

Verify the API Is enabled

This integration requires the BeyondTrust XML API to be enabled. This feature is used by the BeyondTrust Middleware Engine to communicate with the BeyondTrust APIs.

Go to /login > Management > API Configuration and verify that Enable XML API is checked.

Create an OAuth API account

The Zendesk API account is used from within Zendesk to make Remote Support Command API calls to Remote Support.

1. In /login, navigate to Management > API Configuration.
2. Click Add.
3. Check Enabled.
4. Enter a name for the account.
5. OAuth Client ID and OAuth Client Secret is used during the OAuth configuration step in Zendesk.
6. Under Permissions, check the following:
   • Command API: Full Access.
   • Reporting API: Allow Access to Support Session Reports and Recordings, and Allow Access to Presentation Session Reports and Recordings.
7. Click Save at the top of the page to create the account.

Add an outbound event URL

1. Go to /login > Management > Outbound Events.
2. In the HTTP Recipients section, click Add and name it Integration or something similar.
3. Enter the URL to use:
   • If using an appliance ID of default: http://:/ERSPost. The default port is 8180.
   • If using an appliance ID other than default: http://:/ERSPost?appliance= where is the hostname where the BeyondTrust Middleware Engine is installed. The default port is 8180. The is an arbitrary name, but note the value used, as it is entered later in the plugin configuration. This name accepts only alphanumeric values, periods, and underscores.
4. Scroll to Events to Send and check the following events:
   • Support Session End
   • Customer Exit Survey is Completed
   • Representative Survey is Completed
   • Someone Joins a Support Session (Optional)
5. Click Save.

The list of outbound events contains the event just added. The Status column displays a value of OK if communication is working. If communication is not working, the Status column displays an error which you can use to repair communication.

Add a custom link

BeyondTrust custom links can be configured to allow representatives to quickly access the Zendesk item that is associated with the session.

ℹ️

Note

The session must be associated with an open Zendesk ticket by entering that ticket ID in the external key of the session.

1. Browse to Rep Console > Custom Links.
2. Click Add.
3. Enter a name for the link, and then set the URL to https://support.example.com/agent/tickets/%SESSION.CUSTOM.EXTERNAL_KEY% where support.example.com is the Zendesk instance name. If needed, you can use any of the available macros to customize the link according to your specifications.
4. Click Save to save the new link.

Configure plugin

Now that you have configured Zendesk and the B Series Appliance, deploy and configure the Zendesk plugin.

1. Copy the provided plugin ZIP file to the server hosting the BeyondTrust Middleware Engine.

2. Extract the plugin ZIP file to the Plugins folder in the directory where the BeyondTrust Middleware Engine is installed.

3. Restart the BeyondTrust Middleware Engine Windows service.

4. From the server, launch the middleware administration tool. The default URL is http://127.0.0.1:53231.

5. The Zendesk Plugin shows in the list of plugins. Click the clipboard icon to add a new configuration.

BeyondTrust Appliance B Series

The first portion of the plugin configuration provides the necessary settings for communication between the plugin and the B Series Appliance. The configuration sections include:

1. Plugin Configuration Name: Any desired value. Because multiple configurations can be created for a single plugin, allowing different environments to be targeted, provide a descriptive name to indicate how this plugin is to be used.
2. Appliance Id: This can be left as Default or can be given a custom name. This value must match the value configured on the outbound event URL in the B Series Appliance. If outbound events are not being used, this value is still required, but any value may be used.
3. BeyondTrust Appliance B Series Host Name: The hostname of the B Series Appliance. Do not include https:// or other URL elements.
4. BeyondTrust Integration API OAuth Client ID: The client ID of the OAuth account.
5. BeyondTrust Integration API OAuth Client Secret: The client secret of the OAuth account.
6. Locale Used for BeyondTrust API Calls: This value directs the B Series Appliance to return session data in the specified language.
7. Disabled: Enable or disable this plugin configuration.
8. Allow Invalid Certificates: Leave unchecked unless there is a specific need to allow. If enabled, invalid SSL certificates are allowed in calls performed by the plugin. This would allow, for example, self-signed certificates. We do not recommend this in production environments.
9. Use Non-TLS Connections: Leave unchecked unless it is the specific goal to use non-secure connections to the B Series Appliance. If checked, TLS communication is disabled altogether. If non-TLS connections are allowed, HTTP access must be enabled on the BeyondTrust /login > Management > API Configuration page. We strongly discourage using non-secure connections.

ℹ️

Note

When using OAuth authentication, TLS cannot be disabled.

9. Outbound Events Types: Specify which events the plugin processes when received by the middleware engine. Keep in mind that any event types selected here must also be configured to be sent in BeyondTrust. The Middleware Engine receives any events configured to be sent in BeyondTrust but passes them off to the plugin only if the corresponding event type is selected in this section.

• Support Session End
• Customer Exit Survey is Completed
• Representative Survey is Completed

10. Polling Event Types: If network constraints limit connectivity between the B Series Appliance and the middleware engine such that outbound events cannot be used, an alternative is to use polling. The middleware engine regularly polls the B Series Appliance for any sessions that have ended since the last session was processed. At this time, only the Support Session End event type is supported.

ℹ️

Note

One caveat to polling behavior versus the use of outbound events is that if a session has ended but the customer exit survey has not yet been submitted within the same polling interval, the customer exit survey is not processed. This does not apply to representative surveys since the session is not considered to be complete if a representative survey is still pending.

*Polling Interval:** Enter only if polling is used. This determines how often the middleware engine polls the B Series Appliance for sessions that have ended.

11. Retry Attempt Limit: Enter the number of retries that can be attempted if the plugin fails to process an event.
12. Retry Outbound Event Types: Specify which outbound events the plugin retries if it fails to process an event.
13. Retry Polling Event Types: Specify which polling events the plugin retries if it fails to process an event.

Zendesk Server instance

The remainder of the plugin configuration provides the necessary settings for communication between the plugin and the Zendesk instance. The configuration settings include:

• Zendesk API URL: The external API services URL for the Zendesk instance. Example: https://example.zendesk.com
• Zendesk API Username: The username of the API account.
• Zendesk API Token: A token created in Zendesk for API connectivity.

After saving the configuration, click the test icon next to the new plugin configuration. No restart is needed.

Report templates

On the BeyondTrust Middleware Engine server, in the \Plugins\\Templates folder, there are multiple files ending with *.hbs. These are Handlebars template files. These files are used by the plugin to format the session report and exit surveys that are added to the corresponding ticket each time a BeyondTrust session ends or each time a survey is submitted. The templates can be edited if desired.

ℹ️

Note

If you are editing a template, we recommend copying and saving the original in case the changes need to be reverted.

For more information, see the Handlebars website.

Use cases

Generate session key

Support staff can generate a session key that can be given to the end user over the phone or via email to initiate a support session that is automatically associated with the selected ticket.

Import BeyondTrust session data into ticket

Once the session ends, the ticket is automatically updated with information gathered during the session, including:

• Chat Transcript (including files transferred, special actions, and other events)
• System Information (the General section plus other select details such as disk, memory, and network)
• Session Notes
• Surveys (customer and representative)

Jump to configuration item

Support staff can leverage BeyondTrust Jump Technology to access a configuration item associated with a ticket directly from the Zendesk ticket. The following Jump types are available:

• Jump Client (Pinned Client)
• Local Jump (Push and Start Local)
• Remote Jump (Push and Start Remote)
• Remote Desktop Protocol (RDP)
• Shell Jump (Remote Console)

Click-to-chat for help center users

Help Center users can open their submitted tickets and start a chat support session directly from the Zendesk ticket. This allows the user the quickest path to resolution while also providing the representative with the necessary context to assist the user. Sessions can be elevated to full support sessions if enabled and when necessary.

Access ticket from representative console

Using BeyondTrust's custom links ability, a representative can access the associated ticket directly from within the representative console. This saves time searching for the ticket in Zendesk and provides the representative with any issue details, history, or other context to help quickly resolve the issue.