Zoho CRM

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

Introduction to Features

The Zoho CRM extension for Ninja Forms enables you to send your form submission data directly into your Zoho CRM account. Supported modules are:

  • Contacts
  • Leads
  • Accounts
  • Potentials
  • Notes
  • Tasks

In addition to this impressive list of modules, your contacts will automatically be linked with the Account, Potential, Task, and Note. If you create a Lead, it will be linked to the Note and Task.

Custom Fields you create in Zoho are also available for use.

Connecting Ninja Forms to Zoho

Zoho’s new API v2 uses the Open Authorization protocol.  In this method, you will first create in Zoho a “connected app,” the details of which you enter into your WordPress dashboard settings.  Secondly, in WordPress, you’ll click a link we provide that requests access to your Zoho account from WordPress. The final step is for you to approve this access while you are logged into Zoho.

In Ninja Forms, you will need to enter the three values, Client ID, Client Secret, and Authorization Code into the text boxes on the Ninja Forms Zoho CRM Settings section and save the options.

The complete instructions from Zoho on how to generate your Open Auth credentials can be found at this link:

https://www.zoho.com/crm/help/api/v2/#oauth-request

What follows here is a quick start tutorial.

  1.  Visit https://accounts.zoho.com/developerconsole
  2.  Click Add Client Id
  3.  Add your Client ID settings
    1. Client Name  = Ninja Forms
    2. Client Domain = {your website address}
    3. Authorized Redirect URIs = https://accounts.zoho.com
    4. WEB Based

      4. Click Create

      5.  You will be presented with a Client ID and Client Secret; copy and paste these values into the Zoho CRM section of the Ninja Forms Settings page

      6. Back at the Zoho Developer Console, click the triple-dot icon, then select “Self Client”

      7. Scope = ZohoCRM.modules.all

      8. Click View Code

      9. Copy and paste this code in the Authorization Code text box in the Zoho CRM section of the Ninja Forms Settings page

      10. Click Save Options

      11. Click to test your Zoho connection; you should now be fully connected

NOTE: If you are an EU customer, you may need to add the EU endpoint advanced command.  If you are getting an authorization error, please add eu_endpoint to the advanced commands, save your options, and test again.  See the Advanced Commands section for more information.

 

Mapping Form Fields to Zoho

Field mapping is the process of connecting specific fields on your Ninja Form to the CRM field where you’d like the submitted field data to go.  It is best for you to have your Ninja Form already built prior to starting this step. Of course, as you add or modify fields on your form, you always have the opportunity to modify your field maps.

To map fields, go to the Emails & Actions section of your form design, click the “+” to add a new action, and select the “Add to Zoho CRM” action.  You will then see the Add to Zoho Field Mapper, as shown in the image.

 

Add to Zoho field mapper.

For each field to map:

  1. In the “Zoho Field Map” box, click the “+ ADD NEW” button to add a new field map.  Use the “Form Field” drop down icon to bring up a list of all the available fields on your form and click to select the form field you wish to use.  If you want to set a specific value instead of one entered by the site visitor, type in the value you wish to use in this field (see “Setting Constant Values” for more detail).
  2. Click in the “Zoho Field” text box to bring up a list of all the Zoho fields available for receiving the form data.  Click on the field you wish the form data to be sent to. If you are mapping to a custom field, select the ‘-module- Custom ->’ option for this box and move on to the Custom Field box.
  3. The “Custom Field” box is used when you want to map to a custom field.  Type in the name of the custom field exactly as you have it created in Zoho.  To help you get the exact field name, refer to the Advanced Commands section on displaying field names.
  4. The “Custom Field” box is also used for adding custom validation on the given field.  Validation functions are enclosed in curly braces and are placed in the custom field box.  Here is a list of the custom validations:

   {multipicklist} – structures multi-select field for Zoho multi-picklist

   {replace_underscores} – replace underscores with spaces

   {remove_nonnumeric} – ensures value comes in as a number

   {force_boolean} – converts value to true/false

   {convert_date_interval} – converts value to a date interval from submission date

   {format_date} – formats value to a Zoho date format

If you are adding validation to a custom field, simply add the command at the end of the custom field name.  For example, if you have a custom field name of My_Industry and you want to use a pick list, your field would look like this:

My_Industry{multipicklist}

Setting Constant Values

Some values you wish to send to your CRM will always be the same, as opposed to information that the site visitor types into the form. Perhaps the most used example of this would be the Contact Owner – the person in your sales organization who is assigned to the newly created entry.

In this situation, you don’t need to create or select a field from your form, you can simply type in the value you want to send into the Form Field box and then map it to the CRM field where you want that value to go.  

Special Instructions for NF 2.9 Users:

Ninja Forms 2.9 does not have the Actions functionality.  To set a constant value, create a hidden field. Set the “Default Value” to “Custom” and type in the desired value in the custom box that appears.  Go to the advanced settings for the field and map to your desired CRM field. The following example uses “Lead Owner” to demonstrate how to this is accomplished.

Zoho Triggers

NOTE: With Zoho’s new API, workflows are automatically triggered, so you don’t need to turn these triggers on.  This documentation is kept here for those who have yet to migrate to their new API.

If you need to trigger workflow rules, or require approval, you can turn these on by mapping the value true to the Trigger Workflow or Requires Approval field map values as shown in the following image:

About Field Types

When mapping your Ninja Forms’ fields to your CRM account, ensure that your form field is the same type of field that you have in the CRM.  For instance, if your CRM requires a number, you want to ensure that your form field only allows numbers, otherwise it will reject your form submission and the form information won’t make it into your CRM account.

To check your field types in Zoho, go to Setup / Modules / {select your module} as shown in the following screen shots

SetupModulesSelect your Module to View

Field Type Rules

The Data Type dictates what type of data can be sent to any given field in your CRM.  When designing your form, ensure that the field you are sending matches the data type you need.  Here are some types that require special care:

Lookup

Lookup fields have an entry in some other module that must match.  For example, if you map to Campaign Source, ensure that the value you enter matches exactly a Campaign Source that you have created.

Date

Dates should be in the format d/m/Y (ex: 01/01/1970).  For Task Due Date and Potential Closing Date, you have a great feature – the date interval.  Since it may be difficult to set a specific date when you don’t know when a site visitor will submit the form, you can enter an interval ( ex: 2 days , 3 weeks ) and the extension will automatically calculate the future date based on when the form is submitted.

Pick List

A pick list is a specific list of allowed options created inside your CRM.  Ensure that any option or options that you choose match exactly an option in the pick list.  Avoid the use of special characters, like “&” ‘-” “/” wherever possible as Zoho may not recognize the transfer properly.

Boolean

Zoho requires ‘true’ or ‘false’ for boolean fields.  A Ninja Forms checkbox will automatically be converted to the correct values.  If you are creating a different field to send data to a boolean, ensure that the answers are either ‘true’ or ‘false.’

Optional Modules

In addition to creating your Lead or Contact and Account, you have the ability to attach various other modules to your newly created person.

About Potentials

The Potentials module has the following fields available:

    • Name
    • Type
    • Lead Source – match a Pick List value
    • Campaign Source – match a created Campaign
    • Amount – numbers only; may use “,” for thousands separator and “.” for decimal point
    • Closing Date (see “Field Type Rules – Date”)
    • Next Step
    • Stage  – match Pick List value
    • Probability
    • Expected Revenue – numbers only; may use “,” for thousands separator and “.” for decimal point
  • Description

About Notes

The Note module has two fields available:

  • Note Title
  • Note Content

About Tasks

The Tasks module has the following fields available:

  • Task Subject
  • Task Due Date (see “Field Type Rules”)
  • Task Description
  • Task Status(must match a state in your account, e.g., “Not Started”)
  • Task Priority (one of the following integer values: 1 , 2 , 3 )

Advanced Commands

The advanced commands textbox 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:

support
Display advanced communication diagnostics that we at Ninja Forms can use to troubleshoot  any support requests you have.

keep_html_tags

In Ninja Forms 3, text area boxes may have html tags that are removed with code.  If you do not wish to remove html tags before sending, add this command.

eu_endpoint

If your Zoho account is on the EU server ( zoho.eu, instead of zoho.com), use this command to connect to the correct location.  If you don’t know what server you’re on, if you log into zoho.eu and not zoho.com, then you may be on the EU server.

display_fields_module

To view the fields of a given module, add this command, replacing module with the name of a module.  Note that most modules in Zoho are specified as English plurals (Leads, Accounts, Contacts, etc).  You can specify multiple modules by separating them with a dash (Leads-Accounts).

NOTE: This command will pull in the current values every time you view the settings page, so when you have the field names you need, delete this command to speed up the view on your settings page.

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:

Requesting Help

Should you need help and submit a support ticket, do the following to help us find an answer faster for you:

  1. Type in the word “support” in the Advance Commands box
  2. Save your settings
  3. Refresh the page
  4. Take a screen shot including Communication Status, Advanced Commands, and Status

This information can get us working on a solution for you faster.

How helpful was this documentation?

Gold Star Green Light Yellow Light Red Light
Very helpful Helpful Unclear/Unhelpful Not helpful at all