# Salesforce CRM API Integration Pro

# 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'