Salesforce Integration 2015 Bomgar Corporation. All rights reserved worldwide. BOMGAR and the BOMGAR logo are trademarks of Bomgar Corporation; other trademarks shown are the property of their respective owners. TC:9/29/2015
Table of Contents Salesforce Integration Guide 3 Integration Contents 3 Network Considerations 3 Salesforce Configuration 4 Install Bomgar Integration Managed Package 4 Create New Remote Site 4 Set Up Integration Mapping 4 Install Bomgar Integration Unmanaged Package 4 Customize Case Page Layout 5 Add Case Field to Bomgar Session Layout 5 Add Bomgar Username to the User Layout 5 Assign Permission Sets 6 Create New Bomgar Site 6 Add Bomgar Appliance 6 Bomgar Appliance (/login) Configuration 7 Enable XML API 7 Create an API Service Account 7 Add an Outbound Event URL 7 Test the Integration 9 Test Bomgar API User 9 Test Session Key Generation from within Salesforce 9 Test Session Updates 9 CONTACT BOMGAR info@bomgar.com 866.205.3650 (US) +44 (0) 1628 480 210 (UK/EMEA) BOMGAR.COM 2
Salesforce Integration Guide The integration of Bomgar with Salesforce allows you to start a Bomgar support session from within Salesforce. Then the integration allows you to automatically update the incident at the end of the session with the following session information: 1. Chat Transcript (including files transferred, special actions, other events) 2. System Information (General section plus other select details such as disk, memory, network) 3. Session Notes 4. Exit Surveys (Customer and Representative) Integration Contents The integration consists of two primary parts including configuration in both Salesforce and Bomgar. 1. Salesforce Configuration 2. Bomgar Administrative Interface (/login) Configuration Network Considerations Open the following network communication channels for the integration to work effectively. Salesforce > Bomgar Appliance on port 443 Bomgar Appliance > Salesforce on port 80 (optionally 443, depending on your requirements) CONTACT BOMGAR info@bomgar.com 866.205.3650 (US) +44 (0) 1628 480 210 (UK/EMEA) BOMGAR.COM 3
Salesforce Configuration This section consists of importing Bomgar packages, creating Salesforce sites, and various other pieces to prepare Salesforce for the Bomgar Integration. Install Bomgar Integration Managed Package Note: You can obtain the managed package URL from your Bomgar Integration Consultant. Enter the managed package installation URL into the browser, then click the Continue button. 1. On the Install Bomgar Integration screen, select the radio button labeled Install for Admins Only. 2. Click the Install button to install the package. Create New Remote Site In Salesforce.com, click the link labeled Sales in the upper-right of the screen, and select Bomgar Integration. Click Setup. Under Administer > Security Controls > Remote Site Settings, click New Remote Site. Enter Bomgar in the field labeled Remote Site Name, and enter https://your.bomgarappliance.address in the field labeled Remote Site URL, then click Save. Set Up Integration Mapping In Salesforce.com, under Develop > Custom Settings, click the Manage link next to the item labeled Integration Mapping. Click the New button directly above the list of settings. Enter the following from the table below, then click the Save button: Field Label Name 500 Bomgar Field Name external_key Salesforce Field Name Case c Install Bomgar Integration Unmanaged Package Enter the unmanaged package installation URL into the browser, then click the Continue button. 1. On the Install Bomgar Case Integration screen, select the radio button labeled Install for Admins Only. 2. Click the Install button to install the package. If the installation completes successfully, you should see an Install Complete message. Note: You can obtain the unmanaged package URL from your Bomgar Integration Consultant. CONTACT BOMGAR info@bomgar.com 866.205.3650 (US) +44 (0) 1628 480 210 (UK/EMEA) BOMGAR.COM 4
Customize Case Page Layout In Salesforce.com, under Customize > Cases > Page Layouts, click the Edit button next to Case Layout. In the Menu Box at the top, select Buttons, then drag the Generate Session Key or Bomgar Session Key button to the Custom Buttons section. Note that these two buttons are different. See below: 1. Generate Session Key generates the session key server-side via the Bomgar Command API and provides the user with a dialogue containing three things: 1) session key; 2) session key URL; 3) email session key to customer button 2. Bomgar Session Key generates a session key URL via the Bomgar Scripting API that essentially launches the rep console where the standard rep console session key dialogue is displayed. In the Menu Box at the top, select Related Lists, then drag the Bomgar Sessions related list to the related lists section. Scroll down the page and find the Bomgar Sessions section under Related Lists, and click the wrench icon to edit the Bomgar Sessions Related List Properties. Add the following fields from Available to Selected in this order: 1. Primary Customer 2. Primary Representative 3. Start Time 4. End Time 5. Duration Sort By Start Time, Descending, then click the OK button. In the Menu Box at the top, select Buttons again, and disable the New button. Click Save in the Menu Box at the top to save the layout. Add Case Field to Bomgar Session Layout Click Setup. In the Salesforce menu, click under the section titled Build, and select Create > Objects. Click the label Bomgar Session. Scroll down to Page Layouts. Select Edit next to Bomgar Session Layout. Drag the Case Field to the Bomgar Session Detail section. Click Save in the menu box at the top to save the layout. Add Bomgar Username to the User Layout In Salesforce.com, under Customize > Users > Page Layouts, click the Edit button next to User Layout. Drag the Bomgar Username Field to the Additional Information section. Click Save in the menu Box at the top to save the layout. CONTACT BOMGAR info@bomgar.com 866.205.3650 (US) +44 (0) 1628 480 210 (UK/EMEA) BOMGAR.COM 5
Assign Permission Sets In Salesforce.com, under Setup > Manage Users > Permission Sets, click Bomgar Representative Bomgar Case Representative. Click the Manage Assignments button, then use the Add Assignments button to assign this permission set to the appropriate users. Note: The Bomgar Representative - Bomgar Case Integration permission set should be assigned to anyone who needs access to view Bomgar session data. Create New Bomgar Site In Salesforce.com, under Develop > Sites, click the New button. Enter the following, then click the Save button: Field Label Site Label Site Name Active Default Web Address Active Site Homepage Bomgar Bomgar Checked Bomgar Click the Search icon (magnifying glass) and search for Site Login then add it. Click the name of the site you just added. Click the Edit button next to Site Visualforce Pages and add BGIntegration.SessionUpdateHandler to the list of Enabled Visualforce Pages. Ensure that the site is Activated. Add Bomgar Appliance In Salesforce.com, select Bomgar Integration from the button in the far, upper-right. Click the Configuration tab, then click the New button. Enter the following, then click the Save button: Field Label Appliance Name Hostname Username/Password Import System Information Default server.bomgar.com credentials for Bomgar API user checked if the customer wants to pull in System Information CONTACT BOMGAR info@bomgar.com 866.205.3650 (US) +44 (0) 1628 480 210 (UK/EMEA) BOMGAR.COM 6
Bomgar Appliance (/login) Configuration This section consists of making several configuration changes on the Bomgar Appliance. Sign in to your Bomgar /login administrative interface. Enable XML API Under Management > API Configuration, make sure that the Enable XML API box is checked. Create an API Service Account Under Users & Security, create a new User Account. Give this user a password that does not need to be reset, and enable all necessary permissions such as the ability to view reports, generate session keys, and participate in the general queue. Make sure the user has the following settings enabled: Setting Label Password Expires On Allowed to View Support Session Reports Username/Password Import System Information Never Expires (this can be set after the user account is initially saved) View All Sessions Credentials for Bomgar API user Checked if the customer wants to pull in System Information Click the Add User button. After saving the user account, edit the account and make sure that you check the box so that the password does not expire. Add an Outbound Event URL Under Management > Outbound Events, add a New HTTP Recipient. Enter the following values: Name URL Field Label Salesforce Integration http://server.salesforce.com/bomgar/bgintegration_sessionupdatehandler CONTACT BOMGAR info@bomgar.com 866.205.3650 (US) +44 (0) 1628 480 210 (UK/EMEA) BOMGAR.COM 7
Field Label Events to Send Support Session End Customer Exit Survey is Completed Representative Exit Survey is Completed Under Management > Outbound Events, you ll see a list of outbound events, including the one you just added. The status column will have a value of OK if communication is working. If communication is not working, then an error will be displayed in the status column. CONTACT BOMGAR info@bomgar.com 866.205.3650 (US) +44 (0) 1628 480 210 (UK/EMEA) BOMGAR.COM 8
Test the Integration Test Bomgar API User Log into a machine outside of the Bomgar Appliance's network and enter the following URL into a web browser: https://support.example.com/api/command.ns?username=username&password=password&action=generate_ session_key&type=support&queue_id=general&external_key=123 Replace support.example.com with the DNS hostname of the Bomgar Appliance on which the API user was created. Replace USERNAME with the username of the API user account, and replace PASSWORD with the password of the account. The external_key parameter may be removed for testing. The other parameters must be left in place. If the browser returns an XML document tree in <session_key> tags, the test was successful. In most browsers, the following message is expected: "This XML file does not appear to have any style information associated with it." In case of failure: Check the username and password of the Bomgar local user account. This is located in the Bomgar /login administrative interface under /login > Users & Security > User Accounts. Check access in the Bomgar /login interface under Management > Security, Security :: Network Restrictions to confirm that the IP address range for Salesforce is allowed. Check that TCP port 443 is allowed through the firewall to Bomgar. This can be done using telnet as follows: telnet support.example.com 443. If the terminal window returns a blank, black screen and blinking cursor, the port is open. You can also use the port tester tool in the Bomgar /appliance administrative interface. Test Session Key Generation from within Salesforce Log into Salesforce and select the Bomgar Integration app (from the menu on the right side of the screen). Next click the + symbol on the tab strip and click the Cases link. Open an existing Case and click the Generate Session Key button (or the Bomgar Session Key button for customers who chose the URL approach). Once the Generate Session Key button is clicked, a window opens containing a session key, a session URL, and an email button, either in a Salesforce window (for the server-side approach) or in the Bomgar Representative Console (for the URL approach). In case of failure: Make sure that the Salesforce user account is mapped to a Bomgar user account. This user account is set up in the Salesforce Configuration section in this document, entitled Add Bomgar Username to the User Layout. Make sure that TCP port 443 is allowed from Salesforce (in the Cloud) to the Bomgar Appliance (typically the DMZ). In Salesforce, make sure the correct Bomgar values are supplied in the Configuration tab. This setup can be found in the Salesforce Configuration section in this document titled Add Bomgar Appliance. Test Session Updates Use the session URL or session key generated from the previous test section to start a Bomgar session. Make sure that you re logged in to the Bomgar Representative Console as a representative. Once the session is started, send a chat message or two, enter a session note, and then end the session. CONTACT BOMGAR info@bomgar.com 866.205.3650 (US) +44 (0) 1628 480 210 (UK/EMEA) BOMGAR.COM 9
Login to the Bomgar /login administrative interface and go to Management > Outbound Events. Make sure that the Status column for the HTTP Recipient reads OK and doesn t display an error message. Below are various errors that may appear in the status column. Connection timed out this usually means the outbound event never made it to its destination. Use the Bomgar /appliance administrative interface TCP port tester or try to telnet to Salesforce on the appropriate port to see if communication is blocked. A 400 or above error was received this usually means that the Bomgar site created in Salesforce doesn t have the BGIntegration.SessionUpdateHandler Visualforce Page. Connection refused this usually means that network communication is clear, but the destination server has a firewall rule in place or a port is being blocked for incoming requests. Once there are no errors in the Bomgar Outbound Event, you can login to Salesforce as a representative and open the case from which the session key was generated. You will see a list of Bomgar sessions. There should be a row listed for the session you just ran. Note that there could be many sessions listed, so be sure that you are looking at the session you just ran. Bomgar sessions generally show up in Salesforce within 1 minute; however, if there is something delaying the outbound event from posting to Salesforce, it could take longer. If the session doesn t show up in Salesforce, check the Salesforce Error Logs tab to see if there is an error that is keeping the Bomgar Session from posting to Salesforce. CONTACT BOMGAR info@bomgar.com 866.205.3650 (US) +44 (0) 1628 480 210 (UK/EMEA) BOMGAR.COM 10