Joomla vTiger CRM integration using Chronoforms

Want to create a contact form on your Joomla website which automatically feeds into a Vtiger CRM?  Here's how…

My challenge was to take my existing form built on a Joomla 1.5 site using Chronoforms extension (free extension for Joomla) and have the data automatically sent to a vTiger CRM.  I was hoping this wouldn't be hard to do, and to my suprise this was much easier than I thought.  Took a bit a trial-and-error, but below are the steps that worked for me.

To get this to work you don't need to hack any code.  All changes are done in vTiger settings and Chronoform settings.  There is a bit of work to match up your web form with vTiger field names, bu this is explained below. 

The main feature used is the CURL plugin which comes with Chronoforms.  For those looking for the "Ah Ha!" moment, that is what did it for me. 

Before learning about CURL, I was trying to hack a PHP form to do everything for me, basically trying to do what CURL already did. 
That is, my form was already a bit fancy…  I had created a Chronoform which provided an option for users to join a mailing list which I was running using Acajoom, a free newsletter extension for Joomla.  The code worked beautifully where a person who filled out my contact form could opt-in to my newsletter and the Choronoform would handle the subscription.  Also I had another form which did that, plus also integrated with Community Builder (another free Joomla extension) where my Chronoform would ask if a user wanted to subcribe to my website, where my Chronoform would automatically pass the person's name and preferred contact details to Community Builder (and handle all the accound verification stuff).

Because these 2 forms were already doing some fancy stuff, I wanted to add vTiger integration capability, where instead of my contact form being emailed somewhere, it would post the completed form data into vTiger.  I didn't want to affect the existing functionality of the form.  Here's how I got it to work….

1. Install vTiger.  Instructions provided on the vTiger website.
2. Configure webforms module in vTiger
   1. vTiger v5.1 comes with a module for Webforms.  Enable it inside vTiger by going to "Settings >> Module Manager" and making sure Webforms is checked
   2. Configure Webforms module.  Inside your vTiger installation, go to modules >> Webforms and edit Webforms.config.php to the following settings:
      1. $enableAppKeyValidation = "";
      2. $defaultUserName = "admin";
      3. $defaultUserAccessKey = "w3EvRWm9ESFP3Xle"; 
         For this you need to log in to vTiger as Admin, go to the "My Preferences" page, and under "User Advanced Options" copy the key you see there.
      4. $defaultOwner = "standarduser";
Set this to a user inside your vTiger.  "standarduser" is one of the default accounts vTiger sets up for you. I created an account for myself and changed the defaultOwner field to my account's username.

      5. $successURL = "";
I chose not to set my successURL or failureURL as I use Choronoforms for this.

      6. $failureURL = "";
      7. $defaultSuccessAction = "HTML";
      8. $defaultSuccessMessage = "LBL_SUCCESS";
3. OPTIONAL: add custom fields to your vTiger install.  For my needs, I wanted to have a checklist of products the person was interested in.
   1. In vTiger, to add a custom field, go to "Settings >> Module Manager" and next to "Leads" click the icon for "Leads Settings" (the icon might look like a hammer)
   2. Click "Layout Editor"
   3. Add the fields you want.  Make sure to be careful when chosing drop-down menus with pre-defined lists.  Make sure to copy the exact spelling of what you type in as you'll need that later for programming your Joomla form.  The idea is that the values you make available in your drop-down lists (e.g. single select, multiple-select lists and radio buttons) must match the values you put into your Joomla form.
      • TIP!  Use the vTiger Pick List editor to set a custom field to a pre-defined list of values.  Then you can have the same list of options in both your web form and in vTiger.
   4. This is a tricky part.  vTiger puts custom fields into a table called "field" (for MySQL installs it's normally called "vtiger_field").
      1. Option 1:  Use phpMyAdmin.  You need to use a tool like phpMyAdmin to open up the vtiger_field table.   New custom fields are added to the end of the table, so browse it and most likely go to the last page in the table.  There you should see your custom fields.  What you need to do is write down the names of each field (e.g. "cf_543" etc) and make sure you know what that field is used for.  For example, cf_543 in my vTiger is a checkbox for one of my products.  You'll need all the "cf_" field names and know what they store for mapping the fields in your Joomla form.
      2. Option 2: If you have lots of custom fields, a handy tip is to run a simple SQL query, like from phpMyAdmin, which creates a simple table of "fieldname" and "fieldvalue".  Then you can copy this table into text document for referencing later.  Here's a sample SQL query:
         SELECT fieldname,fieldlabel FROM vtiger_field WHERE fieldname LIKE 'cf_%'
4. Install Joomla with Chronoforms
   1. Joomla download and instructions are available at www.joomla.org
   2. Chronoforms is a Joomla extension available here
5. Create your form in Chronoforms
   1. Use the Chronoform built-in form wizard to create your form or create it manually.  You can use any Choronoforms functionality you want, including having it send you an email when the form is submitted.  And you can name form fields to whatever you want.  But here are things you MUST do or consider:
      1. Make sure that for any pre-selection fields (like drop-downs or radio buttons) that you use the exact same spelling as you used in vTiger when setting the value for choices in the fields.  For example, I created a "State" drop-down in my form to list states in my country.  I chose to use state name abbreviations, and made sure the same list existing in vTiger.
      2. Also VERY IMPORTANT is that your form needs to make use of the vTiger standard lead fields and the custom fields you added.  The fields vTiger comes with can be viewed by looking at the file "DatabaseSchema.xml" located in your vTiger installation under the "schema" folder, and you'll find the available standard vTiger Leads table field under "vtiger_leaddetails".  For your custom fields, you can use user-friendly names, like in my case I had a bunch of checkboxes for my products "e.g. Product1, Product2, etc".  You don't have to use the same spellings of field names in your Joomla Chronoform as what vTiger has.  All you need to do is make sure you remember which fields you use, and if you made any custom fields, which field names vTiger set (e.g. the "cf_" fieldnames)
      3. For check-box fields, set the VALUE for checked fields equal to "1".
      4. For drop-down lists or radio buttons, set the default to value="" if you don't want a default value.
6. Use CURL to map fields and send to data to vTiger.   Here's the cool part… Chronoforms supports sending data using CURL.  With this technique it's easy to pass your form data to vTiger.
   1. From the Chronoforms admin tool inside Joomla admin, go to the list of forms and click on the form you created.
   2. From the form settings, click on the plug-ins tab
   3. Click the green check next to "CURL".  This should change CURL option to green.
   4. Click "Save"
   5. Back at the Chronoforms form list, click the checkbox next to your form, then click the "CURL" link on the left side of the form list.  This will take you to the CURL settings for your form.
   6. In the list of fields, you need to map your Joomla form field names to the vTiger field names.  The left side shows all the fields you created in Chronoforms.  The right side needs to contain the corresponding field name in vTiger.  Again, for any field that is not standard inside the vTiger "Leads" table, you'll need to add it to vTiger as a custom field (see steps above).
   7. IMPORTANT!  For the CURL function to work properly, you must pass a hidden field.  At the bottom of the CURL Chronoforms fiels list there is an "Extra fields" area.  Make sure to put in the following:
      ModuleName=Leads
      Optionally you could put this in as a hidden field in your form.  Either way, this is needed for telling vTiger which table you are wanting to modify.
   8. OPTIONAL!  vTiger has a "leads source" field for tracking where a lead came from.  I like to add an extra field to the CURL params which is as follows:
      leadsource=Web Site
      That way I can track which leads came in from the web.
   9. Click the "CURL params" tab and put in a link to the Webforms post module under your vTiger installation.  This would look something like the following:    http://yourdomain/modules/Webforms/post.php

That's it!  Now when you submit your Chronoform in Joomla, the data is sent BEHIND THE SCENES to vTiger and posted into your vTiger Leads table.  This is hidden from the user as CURL processing is done outside the web browser.  So you can even use Chronoforms to still email you the submitted form if you want, and redirect people to whichever web page you want when the form is submitted.

Important Tips / Troubleshooting

Here are some things to remember….

• Make sure your Chronoform form is published for it to work properly
• Make use of Chronoforms built-in anti-spam and field verification for preventing your forms having wrong/bad data from people (including spam bots!)
• Keep your fieldnames to no spaces (e.g. use "Product1" or "Product_1" and not "Product 1")
• Be careful with case sensitivity — your field names and values should match with vTiger when needed:
  • All your fields specified in your CURL params need to match the spellings in vTiger
• Make sure you enable the CURL plugin in the form (see steps 6.1 to 6.4 above)
• Double-check all your settings in the WebForms.config.php file in vtiger/modules\Webform
• Make sure you've enabled the WebForms module in vTiger settings.
• Try to make use of pre-defined lists for drop-down fields, making sure you use the SAME exact lists in both Chronoforms and vTiger (use the vTiger Pick List editor to set fields to pre-defined lists)
• Leads added to your vTiger from your Joomla website are each given a lead ID which is auto-incremented by vTiger.  I would try messing with that.

Enjoy!

Tags: Chronoforms, Joomla, vTiger