All Collections
Integrations & Tech Setup
Salesforce
Salesforce Managed Package - Installation & Configuration Guide
Salesforce Managed Package - Installation & Configuration Guide

Instructions to integrate Ambassador and Salesforce

Crystal McHenry avatar
Written by Crystal McHenry
Updated over a week ago

Before setting up the integration, you will need to fulfill the following requirements:

  • Ambassador contract that includes the Salesforce Managed Package integration

  • Admin level access to the Salesforce organization that you will be integrating

  • Admin or IT level access to the Ambassador account(s) that you will be integrating

  • Ambassador Installation Code or direct installation link, provided by an Ambassador team member

    • Note: You will be prompted to enter payment information in the AppExchange, but you will not be charged if using the code.

For questions about any of the requirements or the below instructions, please contact your Customer Success Manager at Ambassador.

Table of Contents

Installation

Step 1: Install in sandbox

We recommend that you first install the package in your Salesforce sandbox environment so that it can be configured, customized and tested before deploying to Production.

Upon installing, select "Install for Admins Only"
The managed package includes permission sets that you can customize to give users access to an Ambassador App interface when ready. If you install for all users, it will give all users access to the Ambassador Admin interface, which is unlikely a desired result.

Configuration

Step 2: Create a Named Credential*

image.png

Once installed, take the following steps to create a Named Credential in Salesforce

Notes:

  • If you have more than one Ambassador account, you will repeat this step for each.

  • The package ships with an Ambassador API Example named credential, please disregard this and create a new one as instructed above.

  1. From "Quick Find" in Salesforce Setup, type 'name' into the search box

  2. Select Named Credentials

  3. On the right, click the arrow next to New and select New Legacy

  4. Label = Enter your choice of a label

  5. Name = Enter your choice of a name (save this to enter again in Step 4)

  6. For URL, enter https://api.getambassador.com

  7. Set Identity Type to Named Principle

  8. Set Authentication Protocol to Password Authentication

  9. Retrieve the API Username and API Key from the Settings area in your Ambassador account.

    1. With Admin access to Ambassador, go here https://admin.getambassador.com/settings/account and scroll to the bottom section named "API Credentials".

  10. Username = enter API Username

  11. Password = enter API Key (save this to enter again in Step 4)

  12. Deselect the box next to Generate Authorization Header

  13. Select the box next to Allow Merge Fields in HTTP Header

  14. Select the box next to Allow Merge Fields in HTTP Body

  15. Click Save

Populated_Example_Named_Credential.PNG

STEP 3: Create a Company & Activate

Next, follow the steps below to create a "Company" record for your Ambassador account. If you have more than one Ambassador account, you will need to repeat this setup for each of them.

  1. From the App Launcher, open the the Ambassador Admin app

  2. Click on the Companies tab

  3. Click New

  4. Enter the Company Name

  5. Click Save

  6. Click on the Ambassador Setup tab and refresh the page to load the new company

  7. Click Activate

Step 4: Authorize the Company

To authenticate and sync your account, follow these steps to Authorize it.

  1. On the Ambassador Setup page, Click Authorize Credentials

  2. Enter the API Username from Step 2

  3. Enter the Name of the Named Credential that you created in Step 2

  4. Click Authorize

image.png

Step 5: Run Initial Sync

Once you've authorized your Ambassador account, follow these steps to run an initial sync to bring over any existing data from your Ambassador account to Salesforce.

Data brought over from Ambassador includes contacts, share links, short codes, campaigns, segments, and commissions - which will create records for each in our Custom Objects found in the Ambassador App for Salesforce.

  1. When ready, go to the Ambassador Setup object tab and click Initial Sync.

  2. Then, use the "Logs" table on the Setup page to monitor that the sync was successful for each of these custom objects:

    1. Ambassadors

    2. Campaigns

    3. Segments

    4. Campaign Member

    5. Segment Member

    6. Commissions

Notes:

  • The objects will sync asynchronously. Completion time for the initial sync will depend on the volume of existing records in the Ambassador account.

  • During an initial sync, the service will write logs in the lower section showing the results of each object in the sync. Within the logs, there is a refresh button, select it to refresh the table until you see all expected objects.

  • If you’re new to Ambassador, you may not have much data to sync yet. If that’s the case, your future Sync Intervals (Step 6) will incrementally bring in new data and data updates from Ambassador.

  • Remember, the package does not sync data from Salesforce to Ambassador. Instead, it just pushes new data and data updates from Ambassador to Salesforce.

  • If the "Initial Sync" button is grayed out, it has already been executed once before.

  • If you need to re-run an initial sync, click on Advanced Settings > uncheck "Full Sync" > Save. Then, refresh the Ambassador Setup page and click "Initial Sync" button again.

  • If one or more of the object syncs result in an error, click on "Logs" and click into a specific log to view the error details.

    • If you're able to resolve the error or want to re-try, re-run the initial sync using the steps noted above.

    • If you're unable to resolve the error, email your Ambassador Customer Success Manager to ask for help and provide screenshots of the error details.

Step 6: Setup Sync Interval

Once the initial sync is complete, follow these steps to set up the incremental sync interval that will pass new and updated data from Ambassador to Salesforce.

  1. Within Ambassador Setup, click on Advanced Settings.

  2. In the Custom Settings window, click on the Sync Interval drop-down and select between 10-minutes to once daily. Click Save.

Examples scenarios that occur in Ambassador and would be included in the incremental sync:

  • When a newly enrolled ambassador is created in Ambassador

  • When a new commission is created in Ambassador

  • When updates are made to an existing commission in Ambassador

  • When an existing Prospect in Ambassador is enrolled into a campaign

  • When a contact in Ambassador is added to a new segment

  • A new campaign or segment is created in Ambassador

  • When an update is made to a campaign or segment in Ambassador

Notes:

  • You can adjust the Sync Interval at any time.

  • For previous Salesforce package users, the paradigm for syncing has changed. Previously Ambassador would push data into Salesforce upon our own interval schedule. With the new package, it will retrieve data from Ambassador on the sync interval schedule that you set here.

Step 7: Add package field "Referring Short Code" to standard object page layouts and setup mapping

For referral tracking and commission creation, you will need to add our "Referring Short Code" package field to the page layouts of Lead, Contact, Account, and Opportunity standard objects and setup mapping between those that you use.

  1. Add Field name: "Referring Short Code" (GetAmbassador__Short_Code__c) to page layout.

  2. Setup automation to map this field between each object.

Notes:

  • The Referring Short Code is a unique referral code assigned to the ambassador who referred them.

  • We recommend giving atleast read-only permissions to your marketing and sales users to see this field and data.

  • If you use other custom objects and would like to add the referring short code or other details about the ambassador to the custom object, you can create a custom field and follow the recommendation in Step 10 below.

Step 8: Add package Related-Lists to standard object page layouts

For visibility to general users of Salesforce, you will need to add our "Ambassadors" and "Commissions" package related lists to the following standard object page layouts.

  1. Ambassadors - Add to the Contact object

    1. If "Ambassador matching on contacts" is toggled on, their Contact object will be matched with an Ambassador custom object by email and create a Related List on the standard Contact record.

  2. Commissions - Add to the Opportunity object

    1. If a commission record is created for an Opportunity, a related "Commission" record will show up on the Opportunity record.

Step 9: Assign User Permission Settings

The Ambassador package includes two app interfaces with premade permission sets for Ambassador Package admins and general users.

You can assign as-is or clone and modify as needed:

  1. Ambassador Admin - Intended for admins to manage Ambassador companies, settings, objects, and records within Salesforce.

  2. Ambassador - A minimized version of the app interface, intended for general users to interact with the Ambassador related objects and records within Salesforce.

Note: Consider starting with the sample user permissions during initial configuration and make a note to revisit before going live for potential customization needs that you may uncover during implementation.

Step 10: Consider & setup any additional custom field needs

Outside of the Referring Short Code and Related Lists, your team may be interested in mapping data from the Ambassador custom objects, such as the email or other info about a referring ambassador.

Our suggestion is to:

  1. Create custom fields to store values on individual standard records

  2. Create a flow for each standard record type with the following:

    1. Execute on the: After Insert / After Update of the standard record

    2. Check to see if the Short_Code__c is not empty

    3. (Option 1) Look up related Campaign_Member__c and traverses the Ambassador__c relationship to get the:

      1. Ambassador__c.First_Name__c

      2. Ambassador__c.Last_name__c

      3. Ambassador__c.Email__c

    4. (Option 2) Store a "Lookup" Field with the matching Ambassador__c

    5. Then, populate this value into the custom field

Alternatively, you could do this in Apex via a trigger if you need a further level of automation.

Next, if you will be using Salesforce to trigger commission events to Ambassador

First confirm your campaigns are setup in Ambassador, then proceed with using Flow Builder to create a flow automation for each referral event. You should start with our "Lead to Commission" flow template and customize as needed.

Did this answer your question?