Salesforce

⚠️

Important

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

Service desks and customer support organizations using Salesforce.com can integrate with BeyondTrust to centralize their support processes, improve their service levels, and strengthen compliance.

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

• Outbound Support Sessions: Technicians can launch BeyondTrust sessions from within Salesforce cases using the Generate Session Key button.
• Session Updates: BeyondTrust session data is written back to Salesforce tickets. The integration includes chat transcripts, system information, session notes, customer and representative surveys, session recordings, and more details about each BeyondTrust session.

Prerequisites

The requirements to integrate BeyondTrust with Salesforce.com are outlined below. Unless the associated features of an integration component are not used, all of these requirements must be in place prior to starting the integration setup.

Base integration requirements

• A working Salesforce instance
• BeyondTrust BeyondTrust Appliance B Series (physical or virtual) with:
  • Version 17.x or later
  • At least one usable representative console that can generate session keys
  • A working BeyondTrustRemote Support public site through which users can connect to representatives
• Network firewall rules to allow TCP 443 traffic from the appropriate Salesforce instance to reach the BeyondTrust Appliance B Series

Configure Remote Support

Integrating Remote Support with Salesforce requires configuration updates in both applications. All of the steps in this section take place in the B Series Appliance /login administrative interface. Access your B Series Appliance interface by going to the host name of your B Series Appliance followed by /login (for example, https://support.example.com/login).

Verify that the API is enabled

The BeyondTrust Remote Support and Salesforce Integration requires the Remote Support XML API to be enabled. This feature is used from within Salesforce to communicate with the Remote Support APIs.

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

Create an API service account

The Salesforce API Account is used from within Salesforce to make Remote Support Command API calls to Remote Support.

1. Go to Management > API Configuration and click Add to create a new API account.
2. Provide a name for the API account.
3. Under Permissions, check Full Access to the Command API.
4. For the Reporting API, check Allow Access to Support Session Reports and Recordings and Allow Access to Presentation Session Reports and Recordings.
5. Be sure to copy the values for both the OAuth Client ID and OAuth Client Secret for use in a later step.
6. Click Save to create the account.

Set up custom link

Remote Support Custom Links can be configured to allow Representatives to quickly access the Salesforce case which is associated with the session.

1. Browse to Rep Console > Custom Links.

2. In the Custom Links section, click the Add button. Enter a name for the link, then set the URL to:

   • Salesforce Classic: https://salesforce.hostname/%SESSION.CUSTOM.external\_key%

   • Salesforce Lightning: https://salesforce.hostname/lightning/r/Case/%SESSION.CUSTOM.external\_key%/view

     Substitute salesforce.hostname with the Salesforce instance name. If needed, you can use any of the available macros to customize the link according to your specifications.

3. Click Save to save the new link.

Configure Salesforce

Integrating Remote Support with Salesforce requires configuration updates in both applications. Unless otherwise noted, all of the steps in this section take place in the Salesforce.com interface. The development and/or test instances of Salesforce.com should be used initially so that the integration can be thoroughly tested before installation in the production instance.

Install the BeyondTrust managed package

1. Enter the managed package installation URL into the browser, and then click the Continue button.

ℹ️

Note

You can obtain the managed package installation URL from your BeyondTrust technical contact.

2. Select Install for Admins Only and click the Install button.
3. Once you see the Installation Complete message, click the Done button to return to Salesforce.com setup.

Create a new remote site

1. In Salesforce.com, click the link labeled Sales in the upper-right corner of the screen, and select BeyondTrust RS Integration.
2. Under Administer > Security Controls > Remote Site Settings, click the New Remote Site button. Enter the following values:
   • Remote Site Name: BeyondTrustRemoteSupport
   • Remote Site URL: https://your-remote-support-appliance.com.
3. Click the Save button.

Set up integration mapping

1. In Salesforce.com, go to Develop > Custom Settings and click the Manage link next to the item labeled Integration Mapping.
2. Click the New button directly above the list of settings.
3. Enter the following:
   • Name: 500
   • BeyondTrust Remote Support Field Name: external_key
   • Salesforce Field Name: Case__c
4. Click the Save button.

ℹ️

Note

there are 2 underscores in the Field name

Customize the case page layout

1. In Salesforce.com, go to Customize > Cases > Page Layouts and click the Edit button next to Case Layout.
2. In the menu box at the top, select Buttons, and then drag the Generate Session Key or Remote Support Session Key button to the Custom Buttons section.

ℹ️

Note

These two buttons are different.

Generate Session Key: Generates the session key server-side via the BeyondTrust Command API and provides the user with a dialog containing three things: 1) session key, 2) session key URL, and 3) email session key to customer button.

Remote Support Session Key: generates a session key URL via the Remote Support Scripting API that essentially launches the rep console where the standard rep console session key dialogue is displayed.

Remote Support Web Session Key: generates a session key URL via the Remote Support Scripting API that essentially launches the web console where the web session key dialogue is displayed.

Show Case ID: Display the current case internal ID.

3. In the menu box at the top, select Related Lists, and then drag the Remote Support Sessions related list to the Related Lists section.
4. Scroll down the page and find the Remote Support Sessions section under Related Lists, and then click the wrench icon to edit its properties.
5. Add the following fields from Available to Selected in this order:
   • Primary Customer
   • Primary Representative
   • Start Time
   • End Time
   • Duration
6. Sort by Start Time, Descending.
7. Expand the Buttons section and make sure New is unchecked.
8. Click OK.
9. Click the Save button in the menu box at the top to save the layout.
10. When prompted to Overwrite Users Related List Customization, click the No button.

Add the show case ID button

1. Under Customize > Cases > Page Layouts, click the Edit button next to Case Layout.
2. In the menu box at the top, select Buttons, and then drag the Show Case ID button to the Custom Buttons section. This allows technicians to easily get the case ID.

Add quick actions

1. In Salesforce.com, go to Customize > Cases > Page Layouts, and click the Edit button next to Case Layout.
2. In the menu box at the top, select Quick Actions, and then drag the RS Jump and/or RS Session Key quick actions to the Quick Actions section in the Salesforce Classic Publisher area below.
3. Click the Save button in the menu box at the top to save the layout.

Confirm quick actions

1. Go back into the layout you just saved by clicking the Edit button next to its listing.
2. Find the section titled Salesforce1 and Lightning Experience Actions, hover over it, and then click the wrench icon.
3. You should now see the RS Jump and RS Session Key quick actions listed in this section.
4. Click the Save button in the menu box at the top to save the layout.

Remove quick actions for Salesforce Classic

1. Next, remove the quick actions from the Quick Actions section in the Salesforce Classic Publisher section by editing the page layout once more and dragging the RS Jump and RS Session Key quick actions out of the section and back to the menu box.

ℹ️

Note

These quick actions are designed solely for the Lightning UX.

2. Under Customize > Cases > Page Layouts, click the Edit button next to Case Layout.
3. In the Menu Box at the top, click the Save button.

Add case field to Remote Support session layout

1. Select the BeyondTrust RS Integration app, and then click the Remote Support Sessions tab.
2. Click the arrow that is docked to the right side of the screen and click the View Object link.
3. Click the Page Layouts link located directly beneath the page title.
4. Click the Edit link for the BeyondTrust Session Layout.
5. From the Fields menu, drag the Case element to the Information section under BeyondTrust Session Detail.
6. Click the Save button in the menu box at the top to save the layout.

Add Remote Support username to user layout

1. In Salesforce.com, go to Setup from the header menu.
2. Under Customize > Users > Page Layouts, click the Edit button next to User Layout.
3. Drag the BeyondTrust Username field to the Additional Information section.
4. Click the Save button in the menu box at the top to save the layout.

Create new BeyondTrust site

1. In Salesforce.com, go to Setup from the header menu.
2. Under Develop > Sites, click the New button.
3. Enter the following information:
   • Site Label: BeyondTrust
   • Site Name: BeyondTrust
   • Active: [checked]
   • Default Web Address: [BeyondTrust site address]
   • Active Site Homepage: [Search for SiteLogin and add it as the homepage]
4. Click the Save button.

Import BeyondTrust session event types

1. In a new browser tab, navigate to https://salesforce.hostname/resource/BTResources

   Substitute salesforce.hostname with the Salesforce instance name.

2. The browser should download a ZIP archive named BTResources.zip. Navigate to the download location and extract the ZIP contents. It will contain a CSV file named BeyondTrustRemoteSupportEventTypes.csv. You will use this file in a subsequent step.

3. In Salesforce.com, go to Setup from the header menu.

4. Under Administer > Data Management > Data Import Wizard, click Launch Wizard.

5. Click Custom objects > BeyondTrust Remote Support Event Types.

6. Click Add new records.

7. Click CSV, and then click the Choose File button and select the BeyondTrustRemoteSupportEventTypes.csv file.

8. Click Next.

9. Click the Map link, click BeyondTrust Event Type Name, and then click the Map button.

10. Click Start Import.

11. Click OK and verify that that Records Processed has a value of 53 and Status displays Completed.

Configure B Series Appliance

1. Select the BeyondTrust Integration app, and then click Configuration.
2. Click New.
3. Enter the following information:
   • Appliance Name: If you have only one B Series Appliance, it must be named Default.
   • Hostname: Your B Series Appliance hostname.

     ℹ️

     Note

     You must have exactly one B Series Appliance named Default.

   • Client Id: Remote Support API Client Id.
   • Client Secret: Remote Support API Client Secret.
   • Import All BeyondTrust Sessions: Check if you want to import BeyondTrust session data for sessions that were not initiated from within Salesforce.com.
   • Supported Public Portals: A comma-separated list of public portals by name only (for example, Default) that the integration supports. Leave empty if you are supporting only a single public portal.
   • External Recording Base URL: a URL representing the location where external recordings are stored. This is used in the Lightning Experience only, as a way to link to a Remote Support Session Recording from within the session detail view.

     ℹ️

     Note

     lsid=[session_lsid] is automatically be appended to the URL as the unique identifier used in locating the session recording.

   • Outbound Event Token: (optional) a secret token used to validate outbound events from the BeyondTrust Appliance B Series. To use this feature, append &outbound_event_token=[secret_token] to the outbound event URL on the B Series Appliance. The secret_token can be a random alphanumeric string less than 256 characters long.
   • Event Types: Move all supported event types from the Available Event Types list to the Selected Event Types list.
4. Click Save.

Automatic case transition with Apex triggers

The Remote Support middleware plugin provides a .trigger file for use with Salesforce Apex triggers, allowing you to automatically transition cases when exit surveys are completed.

1. Extract the Representative_Exit_Survey_Trigger.trigger file from the middleware plugin download.
2. Open the Developer Console from the Salesforce instance.
3. Open the File > New > Apex Trigger menu.
4. Enter Representative_Exit_Survey_Trigger for the trigger name, and then select BGIntegration__Representative_Exit_Survey_Response__c as the sObject.

ℹ️

Note

The dropdown selection list is in alphabetical order.

1. Open the extracted Representative_Exit_Survey_Trigger.trigger file in notepad.exe, copy the entire contents of the file, and paste the contents into the newly created Apex trigger in the Developer Console.
2. Read and follow the instructions at the top of the newly created trigger for custom configuration and the creation of a customer exit survey trigger (if required).
3. Save the file.
4. The new Apex trigger automatically executes when new Remote Support Exit Surveys are added to any tickets with associated BeyondTrust Remote Support sessions, and transitions cases according to the configuration contained within the trigger.

Configure Lightning Web components

For Salesforce customers who use the lightning experience, several lightning components are available to configure a more flexible UI layout. All of the steps in this section take place in the Salesforce Lightning UI interface.

1. Click the App Launcher button.
2. Click Cases.
3. Select a Case by clicking a Case Number.
4. Select the Settings Gear.
5. Select the Edit Page.
6. Find the Web Component under Custom.
7. Drag a component into the layout.
8. Click Save.
9. Click Back to return to the case screen.

Lightning Web components list

The following Salesforce Lightning components come installed with the BeyondTrust Remote Support and Salesforce Integration.

Case ID Lightning Web component

This component displays the internal case ID for the current case record.

Session key Lightning web component

This component displays:

• Session Key: This key can be used to launch a support session using the support portal with the current case ID as the external key.
• Session Key URL: This URL can be used to launch directly into a support session using the browser with the current case ID as the external key.
• Email Session Key Button: This button sends the session URL to the client that opened the case.
• Generate Session Button: This button launches a remote session for the support representative.

Web session key Lightning Web component

This component displays:

• Session Key: This key can be used to launch a support session using the support portal with the current case ID as the external key.
• Session Key URL: This URL can be used to launch directly into a support session using the browser with the current case ID as the external key.
• Email Session Key Button: This button sends the session URL to the client that opened the case.
• Generate Session Button: This button launches a remote session for the support representative.

Jump To Lightning Web component

This component displays several forms that allow you to Jump to a system using different Jump methods with the rep console.

• Jump To: Search for endpoint and Jump to client.
• Push and Start Local: Jump to pinned host name.
• Push and Start Remote: Jump to a specific target optionally using a Jumpoint.
• RDP Session: Jump to a specific target optionally using a Jumpoint.
• Shell Session: Jump to a specific target optionally using a Jumpoint.
• VPro Session: Jump to a specific target optionally using a Jumpoint.

Web Jump To Lightning Web component

This component displays several forms that allow you to Jump to a system using different Jump methods with the rep console.

• Jump To: Search for endpoint and Jump to client.
• Push and Start Local: Jump to pinned host name.
• Push and Start Remote: Jump to a specific target optionally using a Jumpoint.
• RDP Session: Jump to a specific target optionally using a Jumpoint.
• Shell Session: Jump to a specific target optionally using a Jumpoint.

Set up scheduled job for session import

The session import job can retrieve the Session Data and Rep Exit Survey when the session ends. However since Customer Exit Surveys can be submitted at any point after the customer leaves the session, the survey data can be up to one day out from when the session ended.

To schedule the job run the Anonymous Apex code:

1. Browse to Developer Console on your Salesforce Org.
2. Under the Debug menu, click Open Execute Anonymous Window.
3. Using the sample code below, give the appliance name, time interval in minutes, and job name under which you want the job to run.

ℹ️

Note

The minutes needs to be between 1 and 100.

string applianceName = 'Default';  // This should match your configuration record which is typically 'Default'
Integer interval = 1;  // This can be any value from 1 to 100
string jobName = 'BTSessionDataJob';  // This can be any name you choose
BGIntegration.ScheduleRemoteSupportJob scheduleRemoteSupportJob = new BGIntegration.ScheduleRemoteSupportJob(applianceName, interval, jobName);
scheduleRemoteSupportJob.scheduleJob();

4. Once you have copied and pasted the code above - including your specific values for appliance name, interval, and job name - click Execute to create the job.

ℹ️

Note

Logs can be found in the Developer Console Logs tab where the debug logs also can be found.

If at any point you need to stop the job, it can be found under Scheduled Jobs. Simply delete the entry and repeat the steps above when you are ready to resume it.

Test integration

The following steps take place in Salesforce.com and BeyondTrust and are provided to ensure that the integration works properly. Troubleshooting suggestions are provided with each step in case of failure.

Test session key generation

1. Log in to the BeyondTrust representative console, and then log in to Salesforce.com with the same account. If BeyondTrust and Salesforce.com use different authentication systems, manually assign your BeyondTrust user to your Salesforce.com user via the User Layout in Salesforce.com.
2. Open a case in Salesforce.com.
3. To test client-side session key generation, click the BeyondTrust Session Key button. This should launch the BeyondTrust representative console, subsequently opening the session key dialog box.
4. To test server-side session key generation, click the Generate Session Key button. This should launch a window within Salesforce.com that displays the session key information. In case of failure, make sure the following are true:
   • The Salesforce.com user account is mapped to a BeyondTrust user account as described in this guide.
   • The Salesforce.com API user connection test completes successfully.
   • The BeyondTrust Hostname, Username, and Password fields are set correctly in Salesforce.com under Configuration.

Test BeyondTrust session import

Log in to Salesforce.com as an ITIL user or an admin. Use the BeyondTrust Session Key or Generate Session Key button as described above to start a BeyondTrust session.

1. End the session from the representative console and close any surveys and/or session end messages on the representative and/or customer sides of the session.
2. Refresh the Salesforce.com case from which the session key was generated, scroll down, and check the BeyondTrust Sessions list. There should be an entry for the recent session. If not, make sure the following are true:
   • The API user connection test completes successfully.
   • There are no BeyondTrust errors reported for your Salesforce.com instance in the BeyondTrust /login > Management > Outbound Events list.
   • Make sure no errors are shown in Salesforce.com under the Error Logs tab, which can be seen when the BeyondTrust Integration tab is selected.

Test session key generation (for Lightning UX only)

1. Log in to the BeyondTrust representative console, and then log in to Salesforce.com with the same account. If BeyondTrust and Salesforce.com use different authentication systems, manually assign your BeyondTrust user to your Salesforce.com user via the user layout in Salesforce.com
2. Ensuring that you are in the Salesforce Lightning UX, open a case in Salesforce.com.
3. Click the Session Key tab. You should see the Session Key, the Session Key URL, and the Email Session Key button.
4. Additionally, you should see a Generate Session Key button that can be used to generate a session key (client-side) with the BeyondTrust representative console.
5. Click the Generate Session Key button. This will launch the BeyondTrust representative console, subsequently opening the session key dialog box.

Test Remote Support sessions related list is displayed (for Lightning UX only)

1. In Salesforce (Classic View), go to Setup (from the header menu).
2. Under Administer > Security Controls > Field Accessibility, click BeyondTrust Remote Support Session from the list.
3. Under Choose your view, click the View by Fields link.
4. In the Fields option list that displays, click Case.
5. Click the link next to the type of user (perhaps Standard User) that the related list is not showing.
6. Under the Field-Level Security section, check the Visible box on the row for the type of user you selected in the previous step.

This gives users the level of access they need to view the Remote Support Sessions related list within a Case record.

Use cases

The BeyondTrust Salesforce integration allows you to initiate a support session from the Salesforce Case interface and, at the end of the session, to update the case with the following information:

• Chat Transcript
• File Transfers
• System Information
• Session Notes
• Exit Surveys (Customer and Representative)
• Recordings (Links Only)

High level integration information

Generate session key

A technician can generate a session key from within a case. This session key can be given to a customer to initiate a support session.

Once the support session ends, a detailed report of the session is imported into Salesforce and associated with the case from which the session key was generated.

Import remote support session data into a Salesforce record

Once the Remote Support session ends, Salesforce is automatically updated with information gathered during the support session, including:

• Chat Transcript
• File Transfer Information
• Session Notes
• Customer System Information
• Representatives Involved
• Customers Involved
• Teams Involved
• Session Recordings
• Customer and Representative Survey Results

Jump to configuration item

A technician can leverage Remote Support Jump Technology to access a Remote Support Jump Client directly from a case.

Once the support session ends, a detailed report of the session is imported into Salesforce and associated with the case from which the session was started.

Access Salesforce records from rep console

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

Manually associate sessions with Salesforce records

Whether a representative has just created a case for the current session or has found that one already exists, even sessions originating outside the scope of a Salesforce record can be manually associated with the appropriate item, allowing session details to be automatically added to the case when the session ends.

To make this association, enter the numeric ID of the case into the External Key field while in session. You can use the human-readable record number from Salesforce to easily make this association.

Troubleshoot integration

This is designed to assist members of implementation and support teams who are either installing or supporting the Salesforce Integration. The items listed in this ever-growing document cover potential issues one may encounter when working with the integration, along with steps to take to investigate and alleviate those issues. Salesforce error logs refers to the Error Logs tab in Salesforce, which can be found by selecting the BeyondTrust RS Integration and then clicking the Error Logs tab. This section assumes you have a base knowledge of both Salesforce and Remote Support.

Session key button or tab displays "This site can’t be reached error"

This error appears in Salesforce Classic when the Remote Support Web Session Key button is clicked, and in Salesforce Lightning when the Generate Session Key button under the RS Session Key tab is clicked.

ℹ️

Note

Make sure the B Series Appliance hostname for the B Series Appliance Configuration record is set to a valid hostname and that it is reachable on the network.

Generate session key or web session key button displays "Unauthorized endpoint" error

The full error may look something like this:

Warning: HTTP Exception: Unauthorized endpoint, please check Setup-> Security -> Remote site settings. endpoint = https://support.example.com/oauth2/token.

This error manifests itself in Salesforce Classic when the Generate Session Key button is clicked, and in Salesforce Lightning when the RS Session Key tab is clicked.

ℹ️

Note

Make sure the B Series Appliance hostname for the B Series Appliance Configuration record is set to a valid hostname and that it is reachable on the network.

Nothing happens when the Remote Support session key button is clicked

This button is intended to launch the Remote Support Representative Console.

ℹ️

Note

Ensure:

• the B Series Appliance hostname for the B Series Appliance Configuration record is set to a valid hostname and that it is reachable on the network.
• Make sure the name of the B Series Appliance is set to Default.

Generate session key button or RS session key tab or RS Jump tab displays B Series Appliance configuration “Default” was not found error

This error occurs whenever the default B Series Appliance is not named Default. The name field is different than the hostname field, which contains the B Series Appliance address. The name field is arbitrary, but the first or only one in the list must be set to Default.

ℹ️

Note

Make sure the name of the B Series Appliance is set to Default.

"Error validating parameter ‘queue_ID’: the representative could not be found"

If you get an error stating, Error validating parameter 'queue_id': The representative could not be found, this indicates that the Salesforce user who is trying to generate a session key is not mapped to a Remote Support user. Typically, an LDAP store is used for both Salesforce and Remote Support; thus usernames in each system match exactly.

ℹ️

Note

If an LDAP store is not used and the usernames between Salesforce and Remote Support do not match exactly, the usernames must be manually mapped so that when a session key is generated, a Remote Support user can be found.

For more information, see Add Remote Support username to user layout in this integration installation guide.

"Requested support representative is not available at this time"

If you get an error stating, Requested support representative is not available at this time, this indicates that the Use repRep Console for Session Keys setting is unchecked in the B Series Appliance configuration AND the representative that is mapped to the Salesforce user who generated the session key is not logged into the Remote Support Representative Console.

ℹ️

Note

Have the representative log in to the Remote Support representative console OR check the Use Rep Console for Sessions Keys box and the representative console is launched if it is installed on the representative's workstation.

Support sessions aren’t being written to Salesforce

If support sessions aren't being written in Salesforce, there could be a communication issue. First check to ensure communication is open from Remote Support to Salesforce.

ℹ️

Note

• Login to the Remote Support /login interface and ensure Support Session End is checked on the HTTP Recipient for the Outbound Event. If Support Session End is not checked, check the box, save the HTTP Recipient, then run another support session and see if the record is written to Salesforce.
• If the Outbound Event looks good, login to the Remote Support /appliance interface and run a TCP test to the hostname of the Salesforce instance on port 443. If the TCP test yields a non 200 response, recommend the network team be involved to determine if there is a network block in place, such as a firewall or network rule.
• Ensure the outbound event HTTP Recipient URL is set to http://<middleware.customer.com>/ERSPost?appliance=Default, where <middleware.customer.com> is the hostname of BeyondTrust Integration Middleware.
• Ensure the OAuth Client ID and OAuth Client Secret fields on the B Series Appliance record in Salesforce. It's very common that this OAuth Client Secret value is copied to the clipboard, but the API Account record is never saved in Remote Support /login. We recommend that you copy the value and immediately save the API Account, then paste the value in the B Series Appliance record in Salesforce. Run another support session. If the Support Session record still does not show up in Salesforce, check the BeyondTrust RS Integration Error Logs tab in Salesforce to see if there are any errors that may shed light on why the record isn't being written.

Data is missing from the support session in Salesforce

If data is missing from the Support Session record, it's possible the Remote Support event types have not been updated or only a subset of the event types have been set to be imported for each support session record that is written to Salesforce.

ℹ️

Note

Identify which pieces of data are missing, then check the Selected Event Types field under the B Series Appliance configuration in Salesforce to see if a subset of the events are set to be imported. If you don't see any events, it's possible the Event Types were never imported into Salesforce, as outlined in the Installation guide for this integration.