SalesForce Integration Setup


This is an outline of the steps required to enable the integration between Engage and Salesforce.  The integration process is usually completed by a member of the Proteus team being put in touch with someone in your organization who has a Salesforce Administrator user account. Then the connection can either be completed together on a call or via e-mail.

Items to Consider

  1. The Engage Salesforce integration is only available for Salesforce instances that have API access. Here are two articles from Salesforce to help you know which editions have API access and how to know which edition your organization has.
  2. Does the Salesforce Org have Lightning Experience enabled?  These steps assume so; otherwise, the integration will be done differently (no custom component in Salesforce). Please contact engage@proteus.co directly.
  3. When Engage uses the Salesforce API, it will be operating as the SalesForce user account that was used to authorize ProteusEngage as a “Connected App”.  The user that completes the /admin/sfa-setup setup is the relevant user.  
  4. For Single Sign-On (SSO) to work correctly, Salesforce usernames and Engage usernames must match. (Engage username is user's email address.)


One Day Before the Call (or earlier)

  1. The ProteusEngage Lightning Web Components requires the Salesforce organization to be configured with a custom domain.  The custom domain setup process takes time to complete. (Up to 12 hours.) It is a two-step process:  https://help.salesforce.com/articleView?id=domain_name_overview.htm&type=5

 

During Call

  1. Install the ProteusEngage Salesforce Package that includes our LWC component. User with Salesforce admin access clicks this link:  https://login.salesforce.com/packaging/installPackage.apexp?p0=04t3k0000027BfH  (version 1.2)

    Note:  For a sandbox org, change "login" in the URL above to "test".

  2. Create a Connected App 
    1. Click on App Manager
    2. Click Create a New Connected App (see Screenshot 1)
    3. Enter ProteusEngage as the app name and API name (see Screenshot 1)
    4. Enter engage@proteus.co for the Connected email (see Screenshot 1)
    5. Check Enable OAuth Settings checkbox in API (Enable OAuth Settings) area
    6. Fill in the Callback URL using Customer’s URL:  https://CompanyName.proteusengage.co/admin/sfa-setup



  3. Under the API section mark Access and Manage your data and Perform Requests on your behalf at any time (see below) 
    • Note: Salesforce could change the verbiage of the OAuth Scopes. The latest update verbiage for these two options are "Perform requests at any time (refresh_token, offline_access)" and "Manage user data via APIs (api)".


  4. If using SAML:
    1. Check Enable SAML checkbox in the Web App Settings area (right below API (Enable OAuth Settings) area)
    2. In both Entity Id and ACS URL fields, enter: https://engage-release-admin.proteus.co/ws/saml-proxy-sp
    3. Change Name ID Format to be the one that ends with emailAddress
    4. Configure the app with the desired Profiles and/or Permission Sets so that it is available to the desired SalesForce users
    5. Go to Identity Provider in Setup (hint: use Quick Find)
    6. Click Enable Identity Provider
    7. Create a new certificate
    8. Label it ProteusEngageSSO and click Save
    9. Then Enable it and send Metadata to Proteus IT
    10. Go back to App Manager and click on the ProteusEngage App you previously created
    11. Use the drop-down to choose the certificate just created under SAML
    12. Click Save

  5. Copy the consumer key and secret key into a Word document to be used later
    1. Press save

  6. Look up the SalesForce Organization ID under “Company Information” in SalesForce Setup. Save this out to the same document as the Consumer Key and Secret Key (see below for location of ID)




  7. Configure a CSP Trusted Site for *.proteusengage.co:
    1. Go to Salesforce Setup
    2. Search for CSP and click on CSP Trusted Sites
    3. Select New Trusted Site (near the middle of the page above “Created By”)
    4. Name the trusted site ProteusEngage
    5. Enter the URL for the trusted site: *.proteusengage.co
    6. Click Save



  8. In ProteusEngage, Configure SSO (by an Engage support staff)
    1. Hint: Use the HttpRedirect URL from SalesForce IDP
    2. Hint: SAML Proxy URL is https://engage-release-admin.proteus.co/ws/saml-proxy-sp

  9. In Salesforce, configure the ProteusEngage component onto an Opportunity Detail Page (following these steps but on the Account Detail Page if workspaces are created from SF accounts)
    1. Open an Opportunity Detail Page
    2. Click on the gear icon towards the top of the page to go to Edit Page
    3. Look for the Custom Component named ProteusEngage towards the bottom of the left-hand side, under components (if it does not show up, click Deploy My Domain and then click “Deploy to Users” and repeat steps 2a and 2b)
    4. Drag that button to the desired location on the page
    5. Select it and on the right-hand side paste in the SalesForce Org ID copied previously
    6. Change the ProteusEngage URL to api.proteusengage.co (API URL for a Sandbox environment is different. Consult with your Engage support staff)
    7. Click Assign as Org Default after pop up and choose both Desktop and Phone
    8. Click Save and then click the back button



  10. In Engage, configure the Connected App via https://CompanyName.proteusengage.co/admin/sfa-setup
    1. Fill in the Salesforce Organization Name as whatever you prefer
    2. Paste the saved consumer key, secret key, and SalesForce Organization ID into the Engage Initial Setup UI page



  11. It can take 10-15 minutes after the app is created above before the Connected App is ready to use in Salesforce, but should be ready by now.

  12. (Optional) Test the link between Engage and Salesforce by using (creating if necessary) a testing Opportunity in Salesforce and using the SalesForce component to create a Workspace for it in Engage.

  13. Discuss the process for linking existing Workspaces to Salesforce Opportunities.

  14. Discuss how the Workspace statuses should work with respect to Opportunity Stages (if applicable). 


Things to consider

If the integration is carried out between an Engage non-production environment, such as Engage Stage, and a Salesforce non-production environment, such as Salesforce sandbox, please keep in mind some of the limitations

  • The Engage URLs provided above are to Engage production environment. Engage Client Success Manager must consult with the engineering team on which Engage testing environment can be used.
  • Engage non-production environment might not be turned on 24/7.  Engage Client Success Manager must consult with the engineering team to leave it turn on during the testing duration.
  • The refresh token from Salesforce sandbox might be expired. You will notice that no activities are sent from Engage to Salesforce nor new workspaces/contacts can be created in Engage from Salesforce. When this happens, two things must be done for reconnection:
    1. disconnect the Salesforce sandbox to the Engage testing site (Engage Client Success Manager must consult with the engineering team to disconnect the Salesforce sandbox).
    2. reconfigure the Connected App on Engage testing site again – repeating the above step 10


Questions? Please let us know!  Email engage@proteus.co or your Client Success Manager.