Salesforce CRM

The Salesforce add-on needs to be installed and activated to see the features mentioned in this this documentation.

Not all Salesforce editions have API access enabled. Here are the editions that allow API access by default (as of December 2020):

• • Enterprise Edition
  • Unlimited Edition
  • Developer Edition
  • Performance Edition

Salesforce Authorization

Salesforce uses Open Authorization to connect to your Salesforce account. This process enables you to connect your WordPress site to Salesforce without having to store your Salesforce username and password in the website. You will create a “Connected App” in Salesforce, which has its own Consumer Key and Consumer Secret. This ID and Secret is what you will enter into WordPress to help you gain access to your Salesforce account.

Creating Your Connected App

Please note, if you have trouble creating your Connected App, you may need to talk to your Salesforce account support help, as Ninja Forms cannot provide detailed support for Salesforce accounts. These steps, however, should help you get quickly started:

1. Log into your Salesforce account.
2. Click “Setup” “Connected Apps” “New”.

New Connected App Settings

1. Choose a Connected App name; Salesforce will generate an API name for you based on your chosen name.
2. Provide a contact email address.
3. Select “Enable OAuth Settings”.
4. Callback URL must be: https://login.salesforce.com/services/oauth2/success
5. Chose the following two scopes:
   1. Access and manage your data (api).
   2. Perform requests on your behalf at any time (refresh_token, offline_access).
6. Click “Save”.

Verify Your Connected App

Before continuing, please verify that your Connected App is set up correctly and that you have the following information:

1. Callback URL
   • https://login.salesforce.com/services/oauth2/success
2. Selected OAuth Scopes
   • Manage user data via APIs (API)
   • Perform requests on your behalf at any time (refresh_token, offline_access)
3. Consumer Key (also known as Client ID)
4. Consumer Secret (also known as Client Secret)

Now that your Connected App has been created in Salesforce, you can go to your Ninja Forms settings to connect Ninja Forms to your Salesforce account. Connecting WordPress to your Salesforce account is a two-step process.  Generating your Consumer Key and Consumer Secret is the first step. The second step is generating an Authorization Code.  This second step ensures that only you, who can log into your Salesforce account, is authorized to use that Consumer Key and Secret.

Save Your Consumer Key and Consumer Secret in Ninja Forms

1. In your dashboard, go to Ninja Forms Settings.
2. Scroll to the Salesforce Settings section.
3. Enter your Consumer Key and Consumer Secret.
4. SAVE your settings.

Generate Your Authorization Code

1. After saving your Consumer Key and Consumer Secret, click the link “Click to generate open authorization code”.
   • You will be redirected to Salesforce and asked to log in, if you are not already logged in.
   • After being logged in, you will then be redirected to a page that says “Remote Access Application Authorization”.
   • On this page, the URL that is in the address bar of your browser contains the authorization code you need.
2. Copy the authorization code (the entire address) and paste it into the Authorization Code box in the Salesforce Settings.
3. SAVE your settings.

Generate Your Refresh Token

IMMEDIATELY after saving your authorization code:

1. Click the link “Click to generate refresh token”.
   • Ninja Forms will use your Consumer Key, Consumer Secret, and this Authorization Code to generate a Refresh Token.  This token is what now allows Ninja Forms to submit form data directly into your Salesforce account for you.

Troubleshoot Your Authorization

Callback URL

The callback URL in your Salesforce connected app must match exactly as specified:

https://login.salesforce.com/services/oauth2/success

Open Auth Scopes

The following two scopes must be enabled in your connected app:

Access and manage your data (api)

Perform requests on your behalf at any time (refresh_token, offline_access)

Saving Your Settings

After entering your Consumer Key and Consumer Secret, SAVE your settings before continuing.

After entering your Authorization Code, SAVE your settings.

Click to generate the refresh token IMMEDIATELY after saving.

Connecting to Salesforce Sandbox

To connect to your Salesforce sandbox account, there are some modifications to the steps.  First, please add this snippet to your functions.php file or create a custom plugin to house the code:

add_filter( 'nfsalesforcecrm_set_connection_type' ,'nf_change_salesforce_endpoint');

function nf_change_salesforce_endpoint(){

return ‘test’;
}

Secondly, when setting up your connected app, replace the word ‘login’ in your callback URL with ‘test’.  NOTE: if you have a custom sandbox URL instead of the standard ‘test’, then use that in both the URL and the above code.

Finally, when copying the authorization code, please copy only the code, which appears immediately after “?code=”.

Retrieving Your Salesforce Objects and Fields

Your Salesforce account has objects (ex: Accounts, Contacts, Leads) and fields within those objects (ex: First Name, Last Name, Phone) into which you wish to send your Ninja Forms’ submissions. Once you have successfully connected to your Salesforce account by performing the authorization steps, you can retrieve your objects and fields by:

1. Click the link “Click to retrieve your objects and fields”.

By default, the fields for the Lead object are retrieved. Below the list of fields is a complete list of all the objects you have in your Salesforce account.

If you wish to use different or additional objects:

1. Copy those objects from the object list and paste them into the “Objects to Retrieve” box, separating the objects with a comma “,”. Note: The name of the Object must be used here, not the names of individual fields.
2. Scroll down to the “Save Settings” button and SAVE your settings.
3. Once the page refreshes, click the link “Click to retrieve your Objects and fields”.

The fields for your desired objects are now loaded into Ninja Forms for use in all your forms.

Troubleshoot – redirects to home page

If, when you click to retrieve your objects and fields, you end up on your home page and not back on the settings page, it means that an error occurred in communicating with Salesforce.  If your status message says,“Salesforce has not enabled communication for your account.  Please check with your Salesforce representative”, then your Salesforce account has not been set up to allow communication from outside sources.  You can contact Salesforce to modify your account to an edition that allows access.

Troubleshoot your Objects and Fields:

Ensure that you are entering only Salesforce OBJECTS (not FIELDS).  This step will help you when you are mapping your form.  Salesforce has many objects and many fields; if we were to create a drop down list of every field in every object, you would be scrolling for hours trying to find the field you want.  By entering in only the objects your forms will work with, we can build a custom list of only the fields that are available for you and your form design process is much easier.

Troubleshoot Data not appearing in Salesforce after form submission

If you’ve submitted your form, but do not see the data being created within Salesforce CRM, there may be data missing, such as a required field in Salesforce, or invalid data. You can get details by navigating within your site to Ninja Forms > Settings > Salesforce CRM and viewing the “Status” section.

To view additional information about the data being sent to Salesforce, add the word “support” within the “Advanced Commands” setting.

Next, click the “Save Settings” button.  When the page reloads, additional information regarding errors will appear, allowing you to address those affected fields.

Mapping Your Form Fields to Salesforce

After you have created your form in Ninja Forms, the final step is to map your form fields into where you’d like them to go in your Salesforce account. Here’s how to do that:

1. Go to the Emails & Actions section of your form design.
2. Click “+” to add a new action.
3. Select “Add to Salesforce”.
4. Click “Salesforce Field Map +” to add a new field map.
5. In the Form Field box:
   • Click the gray icon to pull up a list of all your form fields.
   • Select the form field you wish to use.
   • If you want to send a specific value instead of a submitted form value, type the value directly into the box (ex: “3 days”).
     Note: To see the List Field Value fields, you will need to turn on the Developer Mode.
6. In the Salesforce Field, use the drop down list to select to which field in your Salesforce account you wish to send this data.
7. (Optional) Data Handling Instructions lets you do the following:
   • Check for duplicates in this field. If Ninja Forms finds a duplicate in your Salesforce account, a task will be created to notify you of the possible duplicate.
   • Format the field as a date interval. If you want to set a date in the future based on the submission date, click this field and set the form field to the desired date interval.
   • Format the field as a date. Salesforce as a specific date format required, but this format may not be what you want to appear on your form. By selecting this option, your form value will be converted into the date format required by Salesforce.

When you are done, click “Done” and publish your form.  Your form submissions will now be sent to Salesforce. Congratulations!

Advanced Commands

The advanced commands text-box gives you an easy way to change the extension’s functionality without needing any programming experience.  You can add as many of these commands as you want by putting a comma in between them as shown here:

After adding the commands you want, click “Save Options” and then REFRESH your browser page for your changes to take effect.

Here is a list of the current available advanced commands available:

Helpful Hints

Setting Fixed Values

In certain cases, you may want to send a fixed value into your CRM.  For example, you may have a field for lead source and you want it always to say “Web Form Submission”.  To do this, add a row to your Field Map action and, instead of selecting a form field, simply type in the value you want sent, and then map the value to the CRM field you wish.  

In this screenshot example, we want to assign user “bobsmith727” to be in charge of a new opportunity, which we have in our CRM as Opportunity Owner:

Using Checkboxes

Check boxes can be set up by using Ninja Forms’ Single Checkbox.  Set the checked value to ‘true’ and the unchecked value to ‘false’
Note: To see the List Field Value fields, you will need to turn on the Developer Mode.