back to knowledgebase

OpenCRM Standard Webform Package

Updated: 13 August 2020 10:34:08 OpenCRM::Add-in::Web Form

It is possible to post information gathered on a contact form on your website directly into your OpenCRM system. First of all you will need the web form package which can be obtained by contacting us at support@opencrm.co.uk.

Requirements

  • Web form package - this will be supplied to you by us
  • API Keys - this will be supplied to you by us
  • PHP 5.6+ - Your web server must be running PHP 5.6+ in order to run the web forms package in it's standard installation. PHP is used to submit the data from the form to OpenCRM. If you do not have this available, you can use an alternative web scripting language, or if neither that or PHP is available for you, we can host your form processing. Please refer to the "Alternative Hosting Options" section at the end of this FAQ. 

Recommendations

  • Email notification - we recommend adding your own email notifications to your webforms or secondary submission collection so that if there is any issue with your web forms connection to OpenCRM, submissions are not lost. 
  • Spam protection - we recommend enabling spam protection on your webforms to prevent junk data being submitted to your OpenCRM system. The sample forms provided in the standard package have support for Google reCaptcha v2 built in - see customisation options for how to enable this. 

Standard Installation

1. Extract the contents of the web form package to a folder on your website. Make sure that it is possible to run PHP scripts from this folder. Extract all files to the same folder.

2. Open up the file "form_config.php" and set the following variables:

$SYSTEM_URL = 'https://systemname.opencrm.co.uk'; Replace this with the path to your OpenCRM system

$key = ''; You will be provided with two API keys with the form package sent to you - put these in these two variables - they must be in the right order. This authenticates the form with your OpenCRM site
$key2 = '';

3. Three sample forms are provided to give you an starting point (leadform.html, contactform.html and companyform.html) . These should now work and you can customise these yourself (some brief instructions below).

Customisation of Webforms

Adding new fields

You can add as many additional fields to your form as you like. You need to ensure the "name" element on the field matches the name of the field in OpenCRM (you can check this by inspecting the source field you wish to post to in the OpenCRM interface). Alternatively contact OpenCRM support for a list of the field names that you require. 

input type="email" name=email size=30 value="" data-error-text="Please enter a valid email address" required

Validation

The sample forms include some built in validation functionality

  • Mandatory fields - add a "required" tag to the input field:
input data-error-text="Please enter a valid email address" type="email" name=email1 size=30" value="" required
  • Email validation - to check for a valid email address being added, add 'type=email' to your input field:
input type=email name=email1 size=30 value="" data-error-text="Please enter a valid email address" required
  • Error text: To specify the error text which is displayed if validation on a field fails, add or change the "data-error-text' element on the input field:
input type="email" name=email1 size=30" value="" data-error-text="Please enter a valid email address" required
 

Spam Protection

The sample forms have Google reCaptcha (v2) support built in. To enable this:

  • You will need to sign up for a Google reCaptcha account first
  • Find and activate the commented code in the standard web forms, entering your reCaptcha site key into the space provided:
div class="g-recaptcha" data-sitekey="{SITE_KEY}"
 

Thank You message/ page

You can customise the thank you message by editing the file thankyou.php. 

Alternatively, you can change the page which the user is redirected to by changing the following hidden field:

input id="redirect_url" name="redirect_url" readonly="readonly" type="hidden" value="thankyou.php"
 

Additional Standard Webform Features

The following features are available as customisations to the standard package web forms, or can be included on your own custom built forms. 

Sending a notification

To send a notification of the newly created record from the web form, add a hidden field named "notifyuserid" to the webform and set the value to be the user ID (e.g. 1,2,3,4,5) of the user to notify. This needs to be the users ID, not their username or email address. 

input name=notifyuserid size=30 type="hidden" value="21" 

Sending a confirmation email

You can instruct OpenCRM to send a templated email in response to the web form submission to the email address of the record created in OpenCRM (so you will need to make sure the email address field is on your form).

Add a hidden field named "emailtemplate" to the form. Set the value of this field to be the ID of the template which you wish to send as your confirmation email.

input name=emailtemplate size=30 type="hidden" value="123"

Post to Contacts, Leads or Companies

The sample forms are set to post to the correct module in OpenCRM. If you build your own forms and wish to set which module your form posts to, this is done with a hidden form field 'module'. 

input name=module size="30" type="hidden" value="Contacts"
 
You will need to make sure the fields on the form have the right names in accordance to the module you are posting to. For example, the email field on contacts is "email", but on companies it is "email1"

Duplicate check?

To prevent duplicates being created from webform submissions, it is possible to add duplicate check criteria and options to your forms.

  • Add a hidden field "dupecheckfields" to specify the fields you wish to duplicate check on - contact support for help populating this field correctly.
  • Add a hidden field "updateexisting" - to specify whether to update an existing record if a match is found (set to "No" to not update existing records)
  • Add a hidden field "newfieldsonly" - to specify of the fields on your form, which ones should only be updated on new records (i.e. if a matching record is found, these fields won't be updated on this record but all other fields would)
  • Add a hidden field "appendfields" - to specify of the fields on your form, which fields should have the new data APPENDED to them as opposed to replacing the old value. This may be useful for e.g. Description or source fields where you want to maintain a history of information.

 

Advanced Customisation / Building your own forms

If you wish to build your own forms, adapt your existing web forms, or do more advanced customisation, you are free to do this. Read the information below for more details on how to make sure your form works correctly. 

In order for your forms to work, you need to remember the following:

  • Fieldnames need to match those in OpenCRM
  • A hidden field called "module" needs to be set with the correct module to post to
  • the file send_data_ajax.php is used to submit your form data to OpenCRM, and you should either submit to this from your custom built forms, or look at this file and what it does and recreate that for your custom built forms

For more advanced requirements, you may wish to consider building your forms to use your OpenCRM REST API. 

Submitting data to OpenCRM

Option 1 - Local processing (PHP Required)

The standard installation posts the form data to a local PHP script which in turn posts the data to OpenCRM. This is the recommended configuration as it allows you more control and customisation on what happens when submitting data to OpenCRM. 

Data is processed from the web form by a php script "send_data_ajax.php". In the samples provided, this is done via a javascript AJAX call, but you could alternatively set your forms action variable to the script:

form name="webfom" action="send_data_ajax"
 

Data is passed to OpenCRM from the webform package using a SOAP call. The Nusoap component is included in the package in the case that you do not have PHP's in built SOAP client available or enabled. 

The following lines of code are important  - they show the connection being made to the webform service with the nusoap client, the authentication to create a sessionid and then passing the form data to the web form service including the authenticated sessionid. 

send_data_ajax.php
...

$client=new nusoap_client($SYSTEM_URL.'/webformservice.php?wsdl');
//authenticate your API key
$sessionid=$client->call('login', array($key1, $key2));

$result=$client->call('receive_webform_data',array($sessionid, $_SERVER['HTTP_REFERER'],$webform_data));
...
  • $webform_data - the format of this needs to be a serialized array of data in the following format:

$webform_data["firstname"]="Fred";
$webform_data["lastname"]="Bloggs";
$webform_data["email"]="fred@bloggs.com";
 

Option 2 - Alternative to PHP

If you do not have PHP available but do have another web scripting language available, it would be possible to use the send_data_ajax.php file  as an example and re-code in another language. We do not have sample files or code for other languages however.

Option 3 - No scripting available - direct submission

If you have no scripting available on your web server, it is also possible to directly submit the data from the form to processing code on the OpenCRM server. Your web server would then only need to host html forms (plus any associated stylesheet/validation scripts). please note this is not our recommended option and may require additional professional service time or subscription cost to implement this.  Please contact us to discuss your requirements.

Alternative Hosting Options (What if I don't have PHP?)

If you do not have PHP available and do not have another scripting option available or do not have the development knowledge to implement the form processing in that alternative option, we can host your form processing code for you but please note this is not our recommended option and may require additional professional service time or subscription cost to implement this. Please contact us to discuss your requirements. 

Rate This Article
  • 1 star
  • 2 star
  • 3 star
  • 4 star
  • 5 star
Feedback and Comments
captcha code  


You may also be interested in: