This article documents the Salesforce addon that is available in your Higher Logic Vanilla (Vanilla) community. Vanilla Admins can enable it so that staff users can create leads and cases in Salesforce from discussions and comments in Vanilla.
NOTE: This article does not discuss Salesforce OAuth2 SSO functionality. To learn about Salesforce as an authentication provider, see Salesforce SSO using OAuth 2.0.
Features
The Salesforce addon allows users who have the Staff.Allow permission to:
- Link a Salesforce account to a Vanilla user profile.
- Create Salesforce cases and leads from Vanilla discussions and comments (which then appear as "attachments" on your Vanilla discussion for authorized users).
- View Salesforce leads from Vanilla user profiles.
- Sync Vanilla users with Salesforce contacts when a user edits their profile or registers.
- View a snapshot of their Open Cases on Vanilla profile pages (available only with individual connections).
- Sync Vanilla user activity data into Salesforce (as of Release 2022.005; to learn more, contact your CSM). This feature is configured separately from the other features.
Vanilla Admins can alternatively set up a Salesforce global connection, rather than using individual connections as detailed in Connect your Vanilla community to Salesforce, below.
NOTE: Vanilla also offers Single Sign-On (SSO) from Salesforce.
NOTE: Global connection is required to enable syncing Vanilla users with Salesforce contacts upon registration and editing profiles.
Salesforce setup steps
To integrate with Salesforce, you must perform a few steps in your Salesforce account.
TIP: During this process, you will have to copy your Consumer Key and Consumer Secret from Salesforce and paste them into fields in Vanilla. It might be beneficial to have a text editor open and ready.
1. Log in to your Salesforce account.
2. Create a new External Client App in Platform Tools > Apps > External Client Apps > External Client App Manager.
3. Complete the Basic Information required fields (External Client App Name, API Name, and Contact Email) and any optional fields.
4. Check the box to Enable OAuth Settings.
5. Set a Callback URL by appending /profile/salesforceconnect to your community's URL as in the following examples.
- If your community URL is
https://community.example.com/, the Callback URL is https://community.example.com/profile/salesforceconnect. - If your community URL is
https://community.example.com/en/, the Callback URL is https://community.example.com/en/profile/salesforceconnect.
NOTE: The Callback URL protocol must be HTTPS.
6. Use the right arrow to add the following to the Selected OAuth Scopes field.
- Full access (full)
- Perform requests on your behalf at any time (refresh_token, offline_access)
7. Make sure that your other OAuth settings look like the image below.
IMPORTANT: In the Security section, make sure that the third checkbox, Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows, is UNCHECKED.
8. Click Create.
9. On the External Client App's page, click the Settings tab, and under OAuth Settings, click the Consumer Key and Secret button.
NOTE: You might be asked to verify your identity; do so and click Verify to continue.
10. Individually copy the Consumer Key and the Consumer Secret, paste them into a text editor, and save.
Proceed to the next section to continue the set-up process in Vanilla.
Vanilla setup steps
This section describes how to enable and configure the Salesforce addon in your Vanilla account.
1. Access the Dashboard.
2. Navigate to Settings > Addons > Addons.
3. Scroll down to the Salesforce addon and slide the toggle to the right to enable it.
4. Click the settings icon or, in the Dashboard, navigate to Settings > Connections > Salesforce. Both of these actions take you to the Salesforce Settings page.
5. In Connection Settings, click the Edit Settings button.
- This is where you will paste/input the Salesforce Consumer Key and Consumer Secret that you might have pasted into a text editor.
- Input the Salesforce Consumer Key in the Application ID field.
- Input the Salesforce Consumer Secret in the Secret field.
- Leave the default Authentication URL or specify your preferred URL.
- Click Save.
The sections that follow describe the optional settings on the Salesforce settings page.
Connect your Vanilla community to Salesforce
There are two connection options when linking your Vanilla community to your Salesforce account.
NOTE: Regardless of the connection you use, the Salesforce user that you connect to Vanilla must have permissions to create and update Contacts in Salesforce.
Global connection
IMPORTANT: Activity Sync will work only if Global connection is enabled. Refer to Connect your Vanilla community to Salesforce, above, for information.
This option makes it possible for all staff in your Vanilla community to use the same Salesforce connection to create Leads and Cases. All Leads and Cases will show as having been created by this "user." Global connection is required if you want to sync Vanilla users to Salesforce contacts.
NOTE: If a staff user in your Vanilla community has an individual Salesforce connection already established, that will be used instead.
To set the global connection:
- Access the Dashboard.
- Navigate to Settings > Connections > Salesforce.
- In Global Login, click Connect (or right click for the new tab/window options if you want to preserve this page).
Log in to Salesforce and follow the instructions to complete the connection.
Individual connections
This option limits the creation of Leads and Cases to staff in your Vanilla community who have their own Salesforce connection. Leads and Cases they create display as having been created by them.
To set an individual connection:
- Navigate to your Profile page (/profile).
- Access the Social section (/profile/connections).
- In the list of Connections, click Connect next to the Salesforce icon (or right click for the new tab/window options if you want to preserve this page).
Log in to Salesforce and follow the instructions to complete the connection.
Sync user data to Salesforce via Custom Profile Fields
If you have created Custom Profile Fields on the (Settings > Membership) User Profile page (/settings/profile) in Vanilla, you can sync the data in those fields to associated fields in your Salesforce account.
IMPORTANT: To sync Vanilla users to Salesforce contacts, Salesforce requires the First Name and Last Name fields, so make sure that these fields, at a minimum, are ACTIVE. If either of these fields are not toggled on, the sync will fail.
- Toggle on any other fields that you also want to sync to Salesforce.
Enable the data sync
After verifying that the necessary fields are ACTIVE, enable the data sync as described below.
1. Access the Dashboard.
2. Navigate to Settings > Addons > Addons and scroll down to the Salesforce addon.
3. Make sure that the addon is toggled ON (as shown below) and click the settings icon to open the settings page.
4. On the Salesforce settings page, scroll down to Sync users with Salesforce contacts? and:
- make sure that the setting is enabled, and
- click the settings icon to open the Salesforce Contact Sync dialog.
- In the Salesforce ID fields on the dialog, specify the associated Field Name exactly as it appears on the Contact Standard Fields or Contact Custom Fields & Relationships pages in Salesforce (refer to Salesforce Field Name examples, below, for assistance).
TIP: Remember, First Name and Last Name are required in order for this sync feature to work.
5. Click Save to preserve your settings and close the dialog.
6. On the Salesforce settings page, click Save.
Salesforce Field Name examples
Below are two examples that demonstrate the need for specificity in the Salesforce ID field discussed above.
- For Contact Standard Fields, the column to query for the correct "Salesforce ID" value is Field Name.
- For Contact Custom Fields & Relationships, the column to query for the correct "Salesforce ID" value is API Name.
Create a case
Users who have Moderation privileges (Garden.Staff.Allow ) can create a Salesforce case right from a Vanilla discussion or comment.
1. Click the discussion's or comment's ellipsis icon and then select Salesforce - Create Case.
2. On the "create case" form:
- First Name and Last Name - These values are retrieved directly from the discussion or comment.
- Email - This value is retrieved from Salesforce via an API query that is based on the author's email address. If the email address does not exist as a contact in Salesforce, a contact record is created.
- Status - Click the dropdown and make a selection. The values are retrieved from Salesforce via an API.
- Priority - Click the dropdown and make a selection. The values are retrieved from Salesforce via an API.
- Body - This defaults to the body of the discussion or comment.
3. Click Create Case.
The payload of the API call will look like this:
{ "ContactId": "115C3Ct7QAF", "Description": "Charlie Bucket is a poor boy who lives near the Wonka Candy Company. The company's owner,", "Origin": "Vanilla", "Priority": "Medium", "Status": "New", "Subject": "I have a golden ticket."}
When the case has been created, its details display (to Moderators only) on the discussion or comment from which it originated.
Add a lead
Users who have Moderation privileges (Garden.Staff.Allow ) can add a lead in Salesforce right from a Vanilla discussion or comment.
1. Click the discussion's or comment's ellipsis icon and then select Salesforce - Add Lead.
2. On the "add lead" form:
- First Name and Last Name - These values are retrieved directly from the discussion or comment.
- Email - This is the email address of the author of the discussion or comment. If the email address does not exist as a contact in Salesforce, a contact record is created. Conversely, if the email address matches that of an existing lead, the "This Lead already exists" message displays.
- Status - Click the dropdown and make a selection. The values are retrieved from Salesforce via an API.
- Title - The user who adds the lead can include the job title/position of the author of the discussion or comment.
- Company - The user who adds the lead can include the name of the company that employs the author of the discussion or comment.
3. Click Add Lead.
The payload of the API call will look like this:
{ "Company": "Wonka Candy Company", "Description": "I have a golden ticket.", "Email": "willy@wonkafactory.com", "FirstName": "Willy", "LastName": "Wonka", "LeadSource": "Vanilla", "Status": "Working - Contacted", "Title": "President"}
When the lead has been created, its details display (to Moderators only) on the discussion or comment from which it originated.
View open cases
Admins can enable the "display open cases" setting (/plugin/Salesforce) so that Salesforce cases display on users' Profile pages.
Users (Agents)
These users can open their individual Salesforce open cases directly from their Vanilla profiles. These (Agent) users are those who have:
- Admin privileges in your Vanilla community (
Garden.Settings.Manage). - Connected their Salesforce accounts in the Social section (/profile/connections) of their Vanilla Profile page (Profile > Edit Profile > Connections).
Users (non-Agents)
These users can see their Salesforce open cases (cases of which they are the subject) directly from their Vanilla profiles. In this instance, the Salesforce cases that appear are those that contain their email address on Salesforce.
Troubleshooting account linkages
If you are unable to link your Salesforce account and you get a page that says
error=redirect_uri_mismatch&error_description=redirect_uri%20must%20match%20configuration
...make sure that the URL of the Social section of your profile matches the Callback URL that you specified in the Salesforce Enable OAuth Settings (refer to Salesforce setup steps, above).
⭐️ EXAMPLE: If the URL of your profile's Social section is https://community.example.com/somedirectory/profile/connections, the Callback URL should be https://community.example.com/somedirectory/profile/salesforceconnect.
User Activity Sync - sync Vanilla activity data into Salesforce
IMPORTANT: Activity Sync will work only if Global connection is enabled. Refer to Connect your Vanilla community to Salesforce, above, for information.
You can create and set up an object and a trigger in your Salesforce account so that predetermined contact and account activities, that occur in Vanilla, are automatically synced to your Salesforce account.
This makes it easy to automatically create a record in Salesforce (via the trigger that you create) of when someone registers for your Vanilla community, for example, as well as when your contacts and accounts:
- Post discussions and comments
- Submit and vote on Ideas
- Ask and answer questions
- Join a group
- RSVP to an event
...and, these activities are conveniently grouped and easily accessible in your Salesforce interface in the object that you create.
Set up the activity-data sync
Setting up the activity-data sync is a two-step process that requires the involvement of a Salesforce Admin user. The steps are documented in this section and have to be completed in the following order.
1 - Create the Salesforce object, Vanilla Community Activity.
2 - Create the Salesforce trigger, SyncCommunityActivity.
NOTE: If you're not comfortable performing any of the Vanilla-based steps, contact Vanilla Support (support@vanillaforums.com) and request help.
Step 1 - Create the Salesforce object
A Salesforce Admin creates the object, Vanilla Community Activity, in your Salesforce account.
NOTE: Vanilla Community Activity is the activity feed that will display on the Contacts and Accounts page.
1. Create an object in Salesforce and name it Vanilla Community Activity.
IMPORTANT: The object name must exactly match (note the casing and spacing) what appears above; otherwise, the data sync will not work.
2. Create the following fields for the object.
IMPORTANT: The field names and other properties (note the labels, types, casing, and spacing) must exactly match what appears below; otherwise, the data sync will not work.
- FIELD LABEL: Account; DATA TYPE: Lookup(Account)
- FIELD LABEL: Activity Date; DATA TYPE: Date/Time
- FIELD LABEL: Activity Type; DATA TYPE: Text(255)
- FIELD LABEL: Contact; DATA TYPE: Lookup(Contact)
- FIELD LABEL: Description; DATA TYPE: Long Text Area(32768)
- FIELD LABEL: Email; DATA TYPE: Email
- FIELD LABEL: Url; DATA TYPE: URL(255)
- FIELD LABEL: Vanilla Community Activity Name; DATA TYPE: Text(80)
- FIELD LABEL: Vanilla Record ID; DATA TYPE: Number(18,0) (External ID)
- FIELD LABEL: Vanilla User ID; DATA TYPE: Number(18,0)
3. Save your object fields.
Step 2 - Create the Salesforce trigger
A Salesforce Admin creates the trigger, SyncCommunityActivity, in your Salesforce account.
1. Create a trigger in Salesforce and name it SyncCommunityActivity.
IMPORTANT: The trigger name must exactly match (note the casing and absence of spaces) what appears above; otherwise, the data sync will not work.
2. Copy all of the lines of code from below and paste them in the App Trigger field.
trigger SyncCommunityActivity on Vanilla_Community_Activity__c (before insert) {
Set<String> emailSet = new Set<String>();
Set<id> contactIds = new Set<id>();
for (Vanilla_Community_Activity__c ca : Trigger.new){
if (ca.Contact__c == null){
emailSet.add(ca.Email__c);
}else{
contactIds.add(ca.Contact__c);
}
}
List<Contact> con = new List<Contact>();
if (!emailSet.isEmpty()){
con = [SELECT Id FROM Contact WHERE Email = :emailSet Order by CreatedDate DESC Limit 1];
if (con.isEmpty()) {
return;
}
contactIds.add(con[0].Id);
}
List<Contact> acc = [SELECT AccountId FROM Contact WHERE Id in :contactIds];
for(Vanilla_Community_Activity__c ca : Trigger.new){
if (ca.Contact__c == null){
ca.Contact__c = con[0].Id;
}
if (!acc.isEmpty()){
ca.Account__c = acc[0].AccountId;
}
}
}
3. Save the trigger.