Written
This FAQ is an example of sending data to a remote application. In this case it is the vTiger CRM but you can use similar methods to link to other remote applications.
The vTiger CRM has an optional WebForms module and we will use the features offered by this module to transfer the data because it is relatively simple and straightforward. vTiger does also have a much richer and fuller featured API that could also be used if you are familiar with it.
This ChronoForms v4 tutorial is based on a earlier version for ChronoForms v3 written by Craig 'Buz' Busko and published here on his Digital Buz site and on a ChronoForms forum post here by user Ackerman. Much of the text here has been edited from their posts. Many thanks to both of them.
I am writing this after implementing a bridge for a large survey form from ChronoForms into vTiger. I know enough about vTiger to do this, but I am not a vTiger expert and so there may be better ways of handling the vTiger parts of this tutorial.
For my exercise, the form already existed in ChronoForms v4 and was saving to a table in the Joomla database. It is a long survey form with more than 100 inputs. I recommend that you start with something simpler!
You also need a live vTiger installation with the optional WebForms module installed. (If you use a hosted version of vTiger then you will need to check with the documents how to enable a remote form submission.)
In vTiger you will need a Module to save the form results to. In Buz's tutorial he is adding new fields to the standard Leads module; in this example I was working with a new Custom Module.
When you create a module two fields are created for you, one for the record title, the other a serial number for the record id that will be populated by vTiger. Any other fields you will need to add yourself to the vTiger Module.
The ChronoForms form inputs and the vTiger fields for any data that you want to transfer need to match up. They don't need the same name but they should be of the same type and size. Note that vTiger doesn't use standard HTML inputs in all cases so it is worth doing a little planning to get the design of both in sync.
Two particular points to look out for are that vTiger fields that use value lists, e.g. the PickList field do not use separate 'value's and 'text's like HTML select drop-downs so you have to pass over the final 'text' from ChronoForms. Also these vTiger does not permit the characters <, >, / or \ in these PickList values so you need to make sure that they are not used in the ChronoForms values.
I strongly suggest that you start developing with just the first few fields in your vTiger module (use a test form and a test module if necessary) as this can save you time and trouble later.
Configure webforms module in vTiger
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
Configure Webforms module. Using an FTP editor to access your vTiger installation, go to modules | Webforms and edit Webforms.config.php to the following settings:
Configure Webforms module. Using an FTP editor to access your vTiger installation, go to modules | Webforms and edit Webforms.config.php to the following settings:
// This is set to true to enable verification of the submissions
$enableAppKeyValidation = true;
$defaultUserName = "admin";
// For this setting 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.
$defaultUserAccessKey = "aaa123456789aaa";
$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.
// I chose not to set my successURL or failureURL as I use Choronoforms for this.
$successURL = "";
$failureURL = "";
$defaultSuccessAction = "HTML";
$defaultSuccessMessage = "LBL_SUCCESS";
Note: These are mainly Buz's settings but in his tutorial he leaves $enableAppKeyValidation as false, I could not get this to work and it is more secure to enable the AppKey validation by setting this to true. (Thanks to akermann for working out this step.)
Get the vTiger field names
When you create custom fields in vTiger you give them labels but vTiger only uses these for display; inernally it creates a new entry in the vtiger_field database table where all the relevant data about the custom field is stored. You need the value in the fieldname column of this table to identify each data item from ChronoForms to vTiger. You will need to access the database with PHPMyAdmin or the AceSQL extension for Joomla! to get these values.
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 that relate to your module and know what they store for mapping the fields in your Joomla! form.
If you have lots of custom fields, a handy tip is to run a simple MySQL query PHPMyAdmin or AceSQL to create a 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_%';
That's about all you need in VTiger. now for the ChronoForms part . . .
Create your form in Chronoforms
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:
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 (Buz) chose to use state name abbreviations, and made sure the same list existed in vTiger.
Also VERY IMPORTANT is that your form needs to make use of the vTiger standard fields (if there are any in the module you are linking to) and the custom fields you added.
The standard fields that 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". All you need to do is make sure you remember which fields you use, and if you made any custom fields, what the matching vTiger fieldname is.
- For check-box fields, set the value for checked fields equal to "1".
- For drop-down lists or radio buttons, set the default to value="" if you don't want a default value.
Use cURL to map fields and send to data to vTiger
cURL is a method that PHP can use to send data across the internet. ChronoForms comes with a standard cURL action but I recommend that you get and use my {rokbox text=|custom cURL [GH] action| size=|1000,600| }http://greyhead.net/how-to-docs/cfv4-curl-gh-action{/rokbox} for this process. The main difference is that the cURL [GH] action will accept both static and dynamic values i.e. values from the form results and the standard action doesn't accept static values. You can add them to the form data with a Custom Code action but it's simpler to avoid that step.
Drag a copy of the cURL [GH] action into your form On Submit event and open up the action configuration.
In the Target URL box add the URL of the vTiger WebForms module. It will be something like this:
http://www.example.com/modules/Webforms/post.php
The rest of our work will be in the Params/Fields map box. Here we are going to add a list of vTiger field names and the matching ChronoForms value. For a typical form input that might look like:
cf_99={email}
Here cf_99 is the vTiger field name that we got from the vtiger_fields table and email is the matching ChronoForms input name. The curly brackets here tell the cURL [GH] action to use the value submitted from the 'email' input to send to vTiger.
We also need to send some special data to vTiger to tell it how to hand this information when it arrives. The first few lines of the Params/Fields map box need to look like this:
appKey=xxxabcd1234abcd1234xxx moduleName=MyModule leadsource=Customer survey mymodulename={recordname} cf_99={email} . . .
The appKey is the security check; the value of the key can be found in your vTiger site config.inc.php file as the $application_unique_key variable.
The moduleName entry needs to match the name of the vTiger module you want to send the data to.
The leadsource is an optional entry that you can use to identify where the data is coming from if you are sending it to the standard vTiger Leads module.
The mymodulename entry needs to be changed to match the name of the Name field for the module you are sending the data to. The value in this field will be used in vTiger as the entry title so should be set to something meaningful. If there isn't a suitable value in the form results you can use a Custom Code action before the cURL [GH] action to build one and add it to the $form->data array. For my form I used a postcode plus date and time to identify the record.
After that you can add the remaining lines mapping a vTiger field to a form input on each line.
Note: the order of the lines is not important.
Save the form and test.
Testing
To test you should turn on the Show Header in Respose option in the cURL [GH] action and drag a Debugger action into the On Submit event after the cURL [GH] action then save and submit the form. You should then see all of the data from your form; the data that has been sent and received back by the cURL action and a 'Response' from vTiger. Hopefully that is a tick saying that the data has been safely received.
If there is an error then there is very little helpful debugging data sent back from vTiger. You will need to check through item by item to make sure that everything is correct (which is why it helps to start with a short test form). Things to look for are that any vTiger fields marked as 'mandatory' have values; that the URL and variable names do not have any typos - check particularly that the case is correct e.g. moduleName=, not modulename=
When it is working correctly you can delete the Debugger action and turn off Show Header in Response.
Updating
If you later need to add or change fields in vTiger remember that you will need to get the field name from the database table again and update the settings in the cURL [GH] action; vTiger doesn't allow much editing of fields so you may need to delete the exisiting one and create a replacement in which case it will have a different field name.
vTiger v6
The new version requires an additional 'publicid' identifier. Here's how user apaiva described it:
Vtiger 6.2.0 has indeed a new way of handling forms, I'm not a programmer, but looking at their docs here I inferred that they are using an extra field to identify the form in their systems. There is an explanation for using WordPress cforms, they ask to included 'publicid' among the form fields. That got me thinking.
This is what I'm doing:
First you have to create a webform in Vtiger, then you can use the post url and publicid value created by this action. No need to use the form html from Vtiger, we want to use chronoforms, don't we?
The trick is to use the post url from vtiger as the target url in Chronoforms CURL and to include a field publicid in the params/field map equalling the publicid value generated from the vTiger form.
It works for me.