Integrating with Salesforce - Vanilla Success
<main> <article class="userContent"> <p>This document refers to our salesforce Case Creation and Lead Creation addon (Allow staff users to create leads and cases from discussions and comments.).<strong> It does not refer to Salesforce OAuth2 SSO functionality.</strong></p><h2 data-id="requirements">Requirements</h2><p>You must have SSL enabled on your domain. (Your forum must be served over HTTPS).</p><h2 data-id="features">Features</h2><p>This addon allows users who have the <code class="code codeInline" spellcheck="false" tabindex="0">Staff.Allow</code> permission to do the following:</p><ul><li>Link your Salesforce account to your Vanilla user profile.</li><li>Create Salesforce cases and leads from Vanilla discussions and comments.</li><li>Salesforce cases and leads appear as “attachments” on your Vanilla discussion for authorized users.</li><li>View Salesforce leads from Vanilla user profiles.</li><li>Sync Vanilla users with Salesforce contacts when a user edits their profile or registers.</li><li>Visualize a snapshot of their "Open Cases" on Vanilla profile pages (available only with individual connections).</li><li>With Release 2022.005, we now have the added capability to sync user activity data into Salesforce To find out how contact your CSM. </li></ul><p>The Vanilla administrator may alternatively set up a global Salesforce connection rather than using individual connections.</p><p>We also offer single sign-on from Salesforce.</p><h2 data-id="setup">Setup</h2><h3 data-id="on-salesforce%3A-create-configure-application">On Salesforce: Create & Configure Application</h3><ol><li>Log into your Salesforce Account</li><li>Create new Connected App in Salesforce.<ol><li>Platform Tools → Apps → App Manager → New Connected Apps</li><li>Fill the required fields: <strong>Connected App Name</strong>, <strong>API Name</strong>, <strong>Contact Email</strong>.</li><li>Enable OAuth Settings.</li><li>Set a Callback URL by appending <code class="code codeInline" spellcheck="false" tabindex="0">/profile/salesforceconnect</code> to the end of your forum’s URL.<ul><li>If your forum is at <a href="https://forum.example.com/" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://forum.example.com/</code></a>, your Callback URL would be <a href="https://forum.example.com/profile/salesforceconnect" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://forum.example.com/profile/salesforceconnect</code></a>.</li><li>If your forum is at <a href="https://forum.example.com/en/" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://forum.example.com/en/</code></a>, your Callback URL would be <a href="https://forum.example.com/en/profile/salesforceconnect" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://forum.example.com/en/profile/salesforceconnect</code></a>.</li><li>Callback URL must be HTTPS.</li></ul></li><li>Add to Selected OAuth Scopes:<ul><li><strong>Full access (full)</strong></li><li><strong>Perform requests on your behalf at any time (refresh_token, offline_access)</strong></li></ul></li><li>Save. </li></ol></li></ol><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/223/TRUW5B57YO8C.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/223/TRUW5B57YO8C.png" alt="image.png" height="755" width="1168" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h3 data-id="on-vanilla%3A-enable-configure-addon">On Vanilla: Enable & Configure Addon</h3><ol><li>Log into your Vanilla forum.</li><li>Dashboard → Addons, and click the Salesforce addon’s settings icon.</li><li>Fill out ApplicationID (Consumer Key) and Secret (Consumer Secret) as below</li><li>Fill out Authentication URL (usually the default)</li><li>If you plan to sync Users to Contacts, click Enable Global Login button</li><li>Click "Sync users with SalesForce contacts?" toggle</li><li>Click Save</li><li>Click Connect for Global Login</li></ol><p><strong>Where to find your ApplicationID and Secret in Salesforce</strong></p><p>In the app creation section mentioned under API you will see <strong>Consumer Key</strong> (this is the ApplicationID) and <strong>Consumer Secret</strong> (this is the Secret).</p><h2 data-id="connect-your-forum-to-salesforce">Connect your Forum to Salesforce</h2><p>There are two ways to connect your forum to Salesforce.</p><ul><li><strong>Global Connection</strong> - Use this option if you want any agent on your forum to be able to create Leads and Cases using a universal "forum" Salesforce user. Refer to the <em>Global connection</em> instructions, below.</li><li><strong>Individual Connections</strong> - Use this option if you want agents who have users on Salesforce to be able to connect and create Leads and Cases as themselves from the forum. Refer to the <em>Individual connections</em> instructions, below.</li></ul><h3 data-id="global-connection">Global connection</h3><ol><li>As an Administrator, log in to the Vanilla dashboard.</li><li>Go to the Salesforce Addon.</li><li>Next to Global Login click on Connect.</li><li>You will be brought to Salesforce and have to log in.</li></ol><h3 data-id="individual-connections">Individual connections</h3><ol><li>Log in to Vanilla.</li><li>Go to your profile page.</li><li>Edit your profile.</li><li>Click on the Social section (<em>/profile/connections</em>).</li><li>Click <strong>Connect</strong> on Salesforce.</li><li>Follow the instructions to complete the connection.</li></ol><h2 data-id="send-profile-extender-fields-to-salesforce">Send Profile Extender Fields to Salesforce</h2><p>To send custom fields to Salesforce make sure the <code class="code codeInline" spellcheck="false" tabindex="0">SalesForceID</code> field on Vanilla's "Profile Fields" settings is set.</p><p>For "Contact Standard Fields" it should match "Field Name" found in your Salesforce.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/370/OX9T6GW1M0H1.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/370/OX9T6GW1M0H1.png" alt="profileextender1.png" height="175" width="774" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>Would be as below in Vanilla's Profile Field Extender</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/491/WL7KJCYHCPRV.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/491/WL7KJCYHCPRV.png" alt="image.png" height="478" width="1013" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>For "Contact Custom Fields" it should match "API Name" found in your Salesforce.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/865/N16P0BU1603M.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/865/N16P0BU1603M.png" alt="profileextender2.png" height="127" width="564" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>Would be as below in Vanilla's Profile Field Extender</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/720/ALHDE3PCCBG2.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/720/ALHDE3PCCBG2.png" alt="image.png" height="477" width="1020" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h2 data-id="create-cases">Create Cases</h2><p>Users who have Moderation privileges (<code class="code codeInline" spellcheck="false" tabindex="0">Garden.Staff.Allow</code> ) can click on the cog next to a discussion or comment and select <strong>Salesforce - Create Case</strong> to create a case from the content of the post.</p><p>📝 <strong>NOTE</strong>: If the email address of the post's author does not exist as a contact in Salesforce, a contact will be created. </p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/267/PAQOYRTT4ZWT.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/267/PAQOYRTT4ZWT.png" alt="Screen Shot 2019-07-22 at 5.04.27 PM.png" height="1218" width="1326" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>The following data are automatically sent from the forum to Salesforce:</p><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">ContactId</code>: This ID is retrieved from Salesforce via an API query based on the author's email address. If the email address does not exist in Salesforce, a contact is created.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">Status</code>: The status pick-list values are retrieved from Salesforce via API.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">Origin</code>: This is set to 'Vanilla.' It can be manually changed in the forum config (<code class="code codeInline" spellcheck="false" tabindex="0">Salesforce.OriginValue</code>, ask your Customer Success Manager).</li><li><code class="code codeInline" spellcheck="false" tabindex="0">Priority</code>: The priority pick-list values are retrieved from Salesforce via API.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">Subject</code>: This defaults to the title on the discussion.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">Description</code>: This defaults to the body of the discussion or comment.</li></ul><p>📝 <strong>NOTE</strong>: Vanilla doesn't store the values for <strong>First Name</strong> and <strong>Last Name</strong>, but these can be manually added on the above "create case" form by the Moderator in order to complete the Salesforce record. </p><p>The payload of the API call will look like this:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{ "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." } </pre><p>When the Case has been created, the post where it was done will display this to Moderators only:</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/535/HJY6WET2234T.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/535/HJY6WET2234T.png" alt="Screen Shot 2019-07-22 at 5.13.53 PM.png" height="874" width="2050" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h2 data-id="create-leads">Create Leads</h2><p>Users who have Moderation privileges (<code class="code codeInline" spellcheck="false" tabindex="0">Garden.Staff.Allow</code>) can click on the cog next to a discussion or comment and select "Salesforce - Add Lead" to create a lead from the author of the post. If the author of the post's email address does not match the email address of any user already stored as contacts in Salesforce, a contact will be created as well. If the user's email matches the email of an existing Lead, the form will not render and it will display a "This Lead already exists" message.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/755/MLSSV3ZC97JG.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/755/MLSSV3ZC97JG.png" alt="Screen Shot 2019-07-22 at 4.36.15 PM.png" height="1280" width="1324" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>The data sent automatically from the forum to Salesforce during case creation are:</p><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">ContactId</code>: This ID is retrieved from Salesforce via an API query based on the author's email address. If there is no contact for this email address, one is created.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">Email</code>: The email of the author of the comment or discussion. </li><li>'Status': (Salesforce <code class="code codeInline" spellcheck="false" tabindex="0">Status</code>) The status pick-list values are retrieved from Salesforce via API. </li><li><code class="code codeInline" spellcheck="false" tabindex="0">LeadSource</code>: This is set to 'Vanilla'. It can be manually changed in the forum config (<code class="code codeInline" spellcheck="false" tabindex="0">Salesforce.LeadSourceValue</code> , ask your Customer Success Manager).</li><li><code class="code codeInline" spellcheck="false" tabindex="0">Description</code>: The body of the text of the Discussion or Comment.</li></ul><p>Data that the moderator can add to complete the Salesforce record by filling in the Case Creation Form: </p><ul><li> <code class="code codeInline" spellcheck="false" tabindex="0">FirstName</code> </li><li> <code class="code codeInline" spellcheck="false" tabindex="0">LastName</code> </li><li> <code class="code codeInline" spellcheck="false" tabindex="0">Company</code> </li><li> <code class="code codeInline" spellcheck="false" tabindex="0">Title</code> </li></ul><p>The payload of the API call will look like this:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{ "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" } </pre><p>When the Lead has been successfully created, the post where it was done will display this to moderators only: </p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/425/GJPBU2RJI77Z.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/425/GJPBU2RJI77Z.png" alt="Screen Shot 2019-07-22 at 4.40.35 PM.png" height="966" width="2072" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h2 data-id="view-open-cases">View Open Cases</h2><p>Users (Agents) who:</p><ol><li>Have administrative privileges in your <strong>Higher Logic Vanilla (Vanilla)</strong> community (<code class="code codeInline" spellcheck="false" tabindex="0">Garden.Settings.Manage</code>).</li><li>Have connected their Vanilla profiles to their SFDC accounts from their Vanilla community profile page (<strong>Profile > Edit Profile > Connections</strong>).</li></ol><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/XCUSKTCBU9UT/screen-shot-2021-08-31-at-5-23-37-pm.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/XCUSKTCBU9UT/screen-shot-2021-08-31-at-5-23-37-pm.png" alt="Screen Shot 2021-08-31 at 5.23.37 PM.png" height="191" width="1750" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>can view their Open Cases directly from their Vanilla profile. Each case can be opened in Salesforce to view more details.</p><p>Users (non-agents) will also be able to see their Open Cases (cases of which they are the subject). In this instance, the Salesforce cases that will appear will be the ones that contain their email address on Salesforce.</p><p>To enable this feature just toggle the option "<strong>Display Open Cases in Profile Page</strong>?" on the Salesforce settings page on the dashboard.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/7MDJFEYXV4ZL/image.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/7MDJFEYXV4ZL/image.png" alt="image.png" height="1988" width="2880" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h2 data-id="sync-user-activity-data-into-salesforce">Sync user activity data into Salesforce</h2><p>You can sync user activity data into Salesforce so that your Sales, CX, and Support teams will know if and when a contact or account has been active within your Vanilla community. </p><p>When this option is configured, user activity will automatically sync into Salesforce when existing contacts and accounts:</p><ul><li>Register for your Vanilla community</li><li>Post discussions and comments</li><li>Submit and vote on Ideas</li><li>Ask and answer questions</li><li>Join a Group</li><li>RSVP to an event</li></ul><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/IPFIZACYN0UQ/screen-shot-2022-03-08-at-8-37-59-am.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/IPFIZACYN0UQ/screen-shot-2022-03-08-at-8-37-59-am.png" alt="Screen Shot 2022-03-08 at 8.37.59 AM.png" height="1538" width="2880" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h3 data-id="configure-the-salesforce-activity-sync">Configure the Salesforce Activity sync </h3><p>Configuring this user activity sync is a multi-team, multi-step effort. Let's walk through each step in the order they must be completed.</p><p><strong>📝 NOTE</strong>: If you're not comfortable performing any of these steps, contact Vanilla Support to have them help walk you through the process. </p><h3 data-id="step-1-contact-vanilla-support">Step 1 - Contact Vanilla Support</h3><p>The first thing you need to do is contact <strong>Vanilla Support</strong> to have them enable a few required plugins.</p><h3 data-id="step-2-create-salesforce-object-and-trigger">Step 2 - Create Salesforce Object and Trigger</h3><p>A <strong>Salesforce Admin</strong> from your organization must create the Salesforce <em>Object </em>and <em>Trigger </em>in your <strong>Salesforce account</strong>.</p><ul><li>The Vanilla Community Activity Object is the activity feed that will appear on the Contacts and Accounts page.</li><li>The Salesforce Trigger adds a step into the workflow that looks up the contact performing the community activity and associates them to the correct Account in Salesforce.</li></ul><h4 data-id="create-the-vanilla-community-activity-object">Create the Vanilla Community Activity Object</h4><p>Create your Vanilla Community Activity <strong>Object </strong>in Salesforce. You <strong>must</strong> name your object <code class="code codeInline" spellcheck="false" tabindex="0">Vanilla Community Activity</code>. You <strong>must</strong> create the following fields (with the exact same titles, spacing, casing, and associated Data Types):</p><ul><li>Account (Lookup(Account))</li><li>Activity Date (Date/Time)</li><li>Activity Type (Text 255)</li><li>Contact (Lookup(Contact))</li><li>Email (Email)</li><li>Description (LongTextArea 32768)</li><li>Url (URL 255)</li><li>Vanilla Community Activity Name (Text 80)</li><li>Vanilla Record ID (Number 18,0; External ID)</li><li>Vanilla User ID (Number 18,0)</li></ul><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/2BHMTBTGOJ1L/create-sf-object.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/2BHMTBTGOJ1L/create-sf-object.png" alt="create_SF_object.png" height="940" width="1288" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h4 data-id="create-the-associated-object-trigger">Create the associated Object Trigger</h4><p>Once you have created your <code class="code codeInline" spellcheck="false" tabindex="0">Vanilla Community Activity</code> object as described above, you must create the associated <strong>trigger</strong>. To do so:</p><ol><li>Click the <strong>Triggers</strong> menu item. </li><li>Name your trigger <code class="code codeInline" spellcheck="false" tabindex="0">SyncCommunityActivity</code>. </li><li>Paste the lines below in the <strong>App Trigger </strong>field:</li></ol><pre class="code codeBlock" spellcheck="false" tabindex="0">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; } } } </pre><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/MCREN14ZDLGV/create-sf-trigger.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/MCREN14ZDLGV/create-sf-trigger.png" alt="create_SF_trigger.png" height="920" width="1313" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h3 data-id="step-3-finalize-configuration-in-vanilla-community">Step 3 - Finalize configuration in Vanilla community </h3><p>Once the previous steps have been completed, an <strong>Admin </strong>can finalize the configuration in your <strong>Vanilla community</strong>. </p><ol><li>In your Vanilla community, navigate to the <code class="code codeInline" spellcheck="false" tabindex="0">plugin/Salesforce</code> page (append this to your community URL). </li><li>You should see a <strong>Configure Activity Sync</strong> button. Click this button to display a popup window asking you to authenticate with Salesforce. </li><li>Upon successfully authenticating with Salesforce, a toggle will appear in place of the Configure Activity Sync button. Click to enable this toggle. The integration is now enabled.</li></ol><h2 data-id="troubleshooting">Troubleshooting</h2><h3 data-id="i-cant-link-my-account.">I can’t link my account.</h3><p>If you get stuck on a page that says “error=redirect_uri_mismatch&error_description=redirect_uri%20must%20match%20configuration”,</p><p>make sure that the URL you are on when you are in the social section of your profile matches the Callback URL that you set in the configuration.</p><p>Example: If the URL when you are on in your profile’s social section is <a href="https://forum.example.com/somedirectory/profile/connections" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://forum.example.com/somedirectory/profile/connections</code></a>, you should have <a href="https://forum.example.com/somedirectory/profile/salesforceconnect" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">https://forum.example.com/somedirectory/profile/salesforceconnect</code></a> in your configuration.</p><h2></h2> </article> </main>