Salesforce CRM API Integration Pro

This documentation page assumes you have read over the API Integrations overview page. If you have not yet read it, please do so now. We also assume that you have a Salesforce account already. This integration requires that you have Express Forms Pro edition. If you currently have Express Forms Lite, you can purchase an upgrade to Express Forms Pro inside the Craft 3 Plugin Store.

TIP

This integration requires that your site uses HTTPS for the OAuth authentication.

Options

The Salesforce integration allows for 2 different mapping choices:

Salesforce Lead

The Salesforce Lead resource option allows you to send and map your Express Forms submission data to the Salesforce Lead resource.

Salesforce Opportunity

The Salesforce Lead resource option allows you to send and map your Express Forms submission data to a combination of the Salesforce Opportunity, Account and Contact resources. It also includes the following special logic:

  • Field mapping to standard and custom Opportunity, Account and Contact object fields.
    • There are some limitations to types of fields that can be mapped, such as Lookup fields.
  • Express Forms performs a duplicate check on records in the following way:
    1. Check mapped Express Forms field against Account Name field.
      • If no match, create a new Salesforce Account.
    2. Check mapped Express Forms fields against Contact First Name, Last Name and Email fields.
      • If email address exists in Salesforce Contact, update the existing Contact with other details.
      • If no email address match, check if first name and last name exist in Salesforce Contact, then update the existing Contact with all other values including the new email address.
      • If no matches at all, create a new Salesforce Contact.
      • If Account Name matched, assign the new Contact to the existing Salesforce Account.
    3. Create new Opportunity.
      • Attach Opportunity to existing or newly created Salesforce Account.
  • Express Forms will create an Account with the First Name and Last Name mapped to the Contact if you leave the Account Name field empty.
    • This is helpful if you are dealing with customers not necessarily belonging to a company or organization, and just wish to have a Salesforce Account matching the Contact.

Overview

Both integrations observe the same handling for fields. They require that you use HTTPS, and the integrations allow field mapping to standard and custom fields:

  • Text fields:
    • String
    • Textarea
    • Email
    • URL
    • Address
    • Picklist
    • Multipicklist
    • Date/Time fields
  • Numeric fields:
    • Number
    • Phone
    • Currency
  • There are some limitations to types of fields that can be mapped, such as Lookup fields.

Setup

Follow the instructions below to setup Salesforce for Express Forms.

  1. Prepare Express Forms for Integration:
    • Go to API Integrations section inside Express Forms (Express Forms -> Settings -> API Integrations).
    • Click on Setup button for Salesforce.
    • Copy the URL of that page from the browser to your clipboard, e.g. https://hammer.time/admin/express-forms/settings/api-integrations/salesforce and save it for use in a couple mins.
  2. Prepare Salesforce's end for Integration:
    • Open another browser tab and go to Salesforce website and log into your account.
    • On the left navigation menu, click on Apps, then click App Manager.
    • At the top right corner of the page, click the New Connected App button.
    • Fill out the required fields in the Basic Information section.
    • In the API (Enable OAuth Settings) section, click the Enable OAuth Settings checkbox.
    • More fields will appear. In the Callback URL field, paste the URL you copied from Express Forms Salesforce integration setup (needs to begin with https).
    • In the Selected OAuth Scopes field, select the following permissions from the list and click Add arrow button:
      • Access and manage your data (api)
      • Perform requests on your behalf at any time (refresh_token, offline_access)
    • You shouldn't need to fill out any further fields, so skip those and click the Save button.
    • You will be taken to a new page that lists info about your newly created app, including Consumer Key and Consumer Secret values. You will need to copy each of these values.
      • Salesforce gets tricky to navigate, so do yourself a favor and copy and paste these 2 values into a text editor for now, being sure to label each too. You'll save yourself some extra steps later on.
    • At the top middle of the page, click on the Manage button.
    • At the top middle of the next page, click the Edit Policies button.
    • Under the OAuth policies section, adjust the following settings:
      • In the Permitted Users field, be sure that it is set to All users may self-authorize.
      • In the IP Relaxation field, change the setting to Relaxed IP restrictions.
      • Click the Save button at bottom of page.
    • If you copied and pasted the Consumer Key and Consumer Secret values in a text editor, you can skip these next couple steps:
      • To go back to your app to see these values, click on the App Manager navigation item (under Apps)
      • Find your app in the list. Then in the right column, click the down arrow, and then click View.
  3. Setup Integration on your site:
    • Go back to your Craft CP.
    • In the Salesforce setup page, do the following:
      • Paste the Salesforce Consumer Key value into the Consumer Key field in Express Forms.
      • Paste the Salesforce Consumer Secret value into the Consumer Secret field in Express Forms.
      • Additional configuration options:
        • Assign Lead Owner? - Enabling this will make Salesforce assign a lead owner based on lead owner assignment rules in Salesforce.
        • Sandbox Mode - Enable this if your Salesforce account is in Sandbox mode.
        • Using custom URL? - Enable this if you connect to your Salesforce account with a custom company URL such as mycompany.my.salesforce.com.
        • Close Date (required for Opportunity only) - Enter a relative textual date string for the Close Date of the newly created Opportunity (e.g. 7 days).
        • Stage Name (required for Opportunity only) - Enter the Stage Name the newly created Opportunity should be assigned to (e.g. Prospecting).
    • At the top right corner of Express Forms page, click the Save button, which will return you to an OAuth page.
      • If you get an error, you may need to wait up to 10 minutes before trying this again from the time you created the Salesforce app.
    • Accept/authorize the request. You'll be returned back to API Integrations page.
  4. Verify Authorization:
    • Confirm that the integration is highlighted in green with status of Active.
    • That's it! You can now use this integration inside the Form Builder to map fields.

Config File

Using the express-forms-integrations.yaml config file (in your Craft /config/ directory), you can setup API integrations directly in a file, allowing you to have different settings for different server environments, etc.

The Salesforce integration in the config file would look something like this:

Solspace\ExpressForms\integrations\types\Salesforce:
  consumerKey: FAKE86GDS8G76D8G69D8F6DS8097GSFD-98G7SD780A6GDF0S89H7F8D9G6FASD08F6ASD78F6F6S8D6FSF65
  consumerSecret: FAKE5DS6GHF89D7DF8ADSFG796DF7H98FDAS98F6ADF7G86FD98GFDG98FD9G8FD
  accessToken: FAKECV6DVFV87BD8977CV0X87V6FD78VVFDSV98DF76SF8A9F7GSDF98G7DF08DG7FDS980G7SFD78G6VD87C6DF087V6FD87V6FD87V6DF8V6V6
  refreshToken: FAKEVYZC8BX7FGX6B087VX6C8B6CXB87XVC6987Z6BV7C6B5CVX76B97B9V6B598CX76BC8VX7B69CX8V7B68C7
  assignOwner: false
  sandboxMode: false
  customUrl: false
  instance: 'https://na129.salesforce.com'
1
2
3
4
5
6
7
8
9
Last Updated: 4/22/2019, 9:13:45 AM