Vtiger webform custom fields

The vtiger CRM API

For you developers out there, all of the ins and outs of vtiger CRM’s API are fully documented athttp://api.vtiger.com. For those of you not familiar with API’s, API stands for Application Programming Interface. It’s an interface for computers rather than humans.

What does the API do?

To illustrate—you can access the human interface of vtiger CRM by logging in with your username and password. The screens that are shown to you with all of the buttons and links make up the human interface. An API, on the other hand, is an interface for other computers. Computers don’t need the fancy stuff that we humans do in the interface—it’s all text.

What is the benefit of the API?

With an API, vtiger allows other computer systems to inform it and also ask it questions. This makes everyone’s life easier, especially if it means you don’t have to type the same data twice into two systems.

Here’s an example. You have a website where people make sales inquiries and you capture that information as a sales lead. You might receive that information as an email. At that point you could just leave the data in your email and refer to it as needed (which many people still do) or you could enter it into a CRM tool like vtiger so you can keep track of your leads.

You can take it one step further by using vtiger’s API. You can tell your website how to talk to vtiger’s API and now your website can send the leads directly into vtiger, and…Voila! When you log in, the person who just made an inquiry on your website is now a lead in vtiger.

Sending a lead into vtiger CRM from your website

Well, what are we waiting for?! Let’s give it a try. There is a plugin/extension in vtiger called Webforms and it uses the vtiger API to get data into vtiger. In the following exercises, we’re going to:

  • Configure the Webforms plugin
  • Create a webform on your company website

IMPORTANT NOTE: If you want to be able to send leads into vtiger from your website, your vtiger installation must be accessible on the Internet. If you have installed vtiger on a computer or server on your internal network, then you won’t be able to send leads into vtiger from your website, because your website won’t be able to connect with the computer/server that vtiger is running on.

Time for action – configuring the Webforms plugin

OK, let’s roll up our sleeves and get ready to do a little code editing. Let’s take a look first:

  1. Let’s navigate to the Webforms configuration file in vtigercrm/modules/Webforms/Webforms.config.php
  2. Let’s open it up with a text editor like Notepad. Here’s what it might look like by default:

    <?php
    /*+**************************************************************
    *******************
    * The contents of this file are subject to the vtiger CRM Public
    License Version 1.0
    * (“License”); You may not use this file except in compliance
    with the License
    * The Original Code is: vtiger CRM Open Source
    * The Initial Developer of the Original Code is vtiger.
    * Portions created by vtiger are Copyright (C) vtiger.
    * All Rights Reserved.
    *****************************************************************
    *******************/

    $enableAppKeyValidation = true;
    $defaultUserName = ‘admin’;
    $defaultUserAccessKey = ‘iFOdqrI8lS5UhNTa’;

    $defaultOwner = ‘admin’;
    $successURL = ”;
    $failureURL = ”;

    /**
    * JSON or HTML. if incase success and failure URL is NOT
    specified.
    */
    $defaultSuccessAction = ‘HTML’;

    $defaultSuccessMessage = ‘LBL_SUCCESS’;

    ?>

  3. We have to be concerned with several lines here. Specifically, they’re the ones that contain the following:
    • $defaultUserName: This will most likely be the admin user, although it can be any user that you create in your vtiger CRM system.
    • $defaultUserAccessKey: This key is used for authentication when your website will access vtiger’s API. You can access this key by logging in to vtiger and clicking on the My Preferences link at the top right. It needs to be the key for the username assigned to the $defaultUserName variable.
    • $defaultOwner: This user will be assigned all of the new leads created by this form by default.
    • $successURL: If the lead submission is successful, this is the URL to which you want to send the user after they entered their information. This would typically be a web page that would thank the user for their submission and provide any additional sales information.
    • $failureURL: This is the URL which you want to send the user if the submission fails. This would typically be a web page that would say something like, “We apologize, but something has gone wrong. Please try again”.
  4. Now you’ll need to fill in the values with the information from our own installation of vtiger CRM.
  5. Save the Webforms.config.php and close it. We’ve finished completing the configuration of the Webforms module.

What just happened?

We configured the Webforms module in vtiger CRM. We modified the Webform plugin’s configuration file,Webforms.config.php. Now the Webforms module will:

  • Be able to authenticate lead submissions that come from your website
  • Assign all new leads to the admin user by default (you’ll be able to change this)
  • Send the user to a thank you page, should the lead submission into vtiger succeed
  • Send the user to an “Oops” page, should the lead submission into vtiger fail

How to set up a webform on your website

Now that we have everything configured on the vtiger side of things, let’s make some simples changes on your website that will allow you to send a lead from your website directly into vtiger.

Time for action – setting up a lead form on your website

Here is where some basic knowledge of HTML will come into play:

  1. You’ll need a page on your website that will “host” the webform. Open up that web page with your HTML editor.
  2. Now, in the body of the web page, (in between the <body> and </body> tags) create a form using the HTML code below. Where you can see VTIGER-URL you need to put it in the URL of your vtiger installation:

    <form method=”POST” action=”http://[VTIGER-URL]/modules/Webforms/
    post.php”>
    <input type=”hidden” value=”Leads” name=”moduleName” />
    <table>
    <tbody>
    <tr>
    <td><label>Last Name</label></td>
    <td><input type=”text” name=”lastname” value=”” /></td>
    </tr>
    <tr>
    <td><label>First Name</td>
    <td><input type=”text” name=”firstname” value=”” /></td>
    </tr>
    <tr>
    <td><label>Company</td>
    <td><input type=”text” name=”company” value=”” /></td>
    </tr>
    </tbody>
    <table>
    <input type=”submit” value=”Submit” />
    </form>

  3. Now save your web page.
  4. Now go to the URL of the web page that you just added the webform to.
  5. Fill out all of the fields. Note that if the fields are required in vtiger and they are not all completed, the lead submission will fail.
  6. Submit the form.
  7. Log in to vtiger and go to Sales | Leads.
  8. You should see the new lead in your list of leads.

What just happened?

We used the vtiger CRM API to get data from an external system into your installation of vtiger. We used the Webform component of vtiger to create a form on your company website. Now when visitors to your website make a sales inquiry, that data will go straight into vtiger.

How to use custom fields in a webform

Now suppose that you have customized your Leads module and you have 20 or 30 custom fields. You may have very specific information that you want to capture in that first step so that the next step in the sales process can be more successful and move the lead closer to a potential sale.

In this case, you’ll need to modify the plain webform from the example above and include form fields that will connect with your custom fields once the lead hits vtiger. Let’s try it.

Time for Action – using custom fields in a webform

  1. Once again, you’ll need a page on your website that will “host” the webform. Open up that web page with your HTML editor.
  2. Now, in the body of the web page, (in between the <body> and </body> tags) create a form using the HTML code below. Where you can see VTIGER-URL you need to put it in the URL of your vtiger installation:

    <form method=”POST” action=”http://[VTIGER-URL]/modules/Webforms/
    post.php”>
    <input type=”hidden” value=”Leads” name=”moduleName” />
    <table>
    <tbody>
    <tr>
    <td><label>Last Name</label></td>
    <td><input type=”text” name=”lastname” value=”” /></td>
    </tr>
    <tr>
    <td><label>First Name</td>
    <td><input type=”text” name=”firstname” value=”” /></td>
    </tr>
    <tr>
    <td><label>Company</td>
    <td><input type=”text” name=”company” value=”” /></td>
    </tr>
    </tbody>
    <table>
    <input type=”submit” value=”Submit” />
    </form>

  3. Here’s where we’ll add the custom field. We have to create a new HTML input element and name it to match the name that our custom field has in the database.
  4. First, we have to find out what the field name is in the database. To do this execute the following on your MySQL server:

    use database vtigercrm;

    SELECT fieldname FROM vtiger_field WHERE fieldlabel LIKE “Custom
    Text Field” AND tablename = “vtiger_leadscf”;

  5. Note that you’ll have to modify a couple of things:
    • You’ll have to substitute vtigercrm in the statement use database vtigercrm; with the name of your vtiger database
    • You’ll have to substitute “Custom Text Field” in the following SELECT statement with the label of your custom field
  6. MySQL will return the field name that you’ll use in your webform. That is the value that you’ll need to use on your webform. In this example that value is cf_476.
  7. Now edit your web page to look like the following:

    <form method=”POST” action=”http://[VTIGER-URL]/modules/Webforms/
    post.php”>
    <input type=”hidden” value=”Leads” name=”moduleName” />
    <table>
    <tbody>
    <tr>
    <td><label>Last Name</label></td>
    <td><input type=”text” name=”lastname” value=”” /></td>
    </tr>
    <tr>
    <td><label>First Name</td>
    <td><input type=”text” name=”firstname” value=”” /></td>
    </tr>
    <tr>
    <td><label>Company</td>
    <td><input type=”text” name=”company” value=”” /></td>
    </tr>
    <tr>
    <td><label>Custom Text</td>
    <td><input type=”text” name=”cf_476″ value=”” /></td>
    </tr>
    </tbody>
    <table>
    <input type=”submit” value=”Submit” />
    </form>

  8. Now save your web page.
  9. Now go to the URL of the web page that you just added the webform to.
  10. Fill out all of the fields. Note that if the fields are required in vtiger and they are not all completed, the lead submission will fail.
  11. Submit the form.
  12. Log in to vtiger and go to Sales | Leads.
  13. You should see the new lead in your list of leads with your custom field, Custom Text Field, populated.

What just happened?

We created a form from HTML and inserted it onto a web page of your company website. We looked through vtiger CRM’s MySQL database and found the database name of your custom field. We then used the database name of your custom field in the webform. Now you can add as many custom forms as you would like to your webform.

Summary

In this article, we learned that vtiger has the power to integrate with external systems. In particular:

  • vtiger CRM’s API is an interface to external systems
  • The Webforms module in vtiger is a powerful tool that you can use to eliminate the need for double-entry of data
  • We were able to create a “portal” on your company website where prospective customers can make a sales inquiry and directly insert that inquiry into your installation of vtiger CRM for followup

source:http://www.packtpub.com/article/how-to-integrate-vtiger-crm-external-systems-website