Form Handlers Overview

About

Form handlers collect data from forms then automatically create or update records within Insightly Marketing.

Prior to creating a form handler, users should setup their Web Tracking Domain for their website.

How do Form Handlers Work?

Form handlers collect data from a form located on a website; Insightly handles the data that is collected and subsequently creates or updates a Prospect within Insightly Marketing. Form handlers eliminate the need for manual data entry after a Prospect has filled out a form. When a form handler is created, it can also be used as the form itself or, the fields from a preexisting form can be mapped to Prospect fields in Insightly Marketing and the form handlers HTML can be added to the HTML of the preexisting form.

Insightly form handlers will only accept POST form submissions; "multipart/form-data" posts will not be accepted because form handlers cannot support file uploads.

Prior to creating a form handler, users should setup their Web Tracking Domain for their website. Users will need to add the JavaScript tracking code for the HTML of a form on their website. When a form handler has been created, the form's HTML can be generated. This HTML code can then be added to a website and it will contain all the fields from the form handler in order.

In addition to generating and adding the form handler HTML to a website, Insightly will also create a Form Submit URL which will connect a preexisting form to a form handler.

Spam

When a form submission is received, Insightly will check the IP address and the user. If five or more form submissions are received in a five minute window from the same IP address and user, Insightly will not process the submission and it will be discarded. The submitter will receive an HTTP 500 error - this occurs even if the user is blank or null. This spam check occurs in finish action sequences for form submissions, redirect links, hosted files, and list emails.

Users can also utilize reCAPTCHA v3 to help with web hosts to distinguish between human and automated access to websites. The necessary JavaScript resource will need to be included as well as adding a few attributes to the HTML button. Review the Setup reCAPTCHA v3 for a Form section of this help article for more information.

Additionally, when a form submission is received, Insightly will check whether the First Name or Last Name form fields contain any URL, potentially using a Regex. If either of those fields contain a URL, Insightly will return an HTTP 500 error and will discard the form submission entirely.

A honeypot field is a hidden field that is visible to bots, but not humans. When a bot fills out a form, the bot sees the hidden field and fills it out. Insightly will not process any form submissions that contain any value in the honeypot field, but the bot will receive the form success message. The honeypot field can be added to forms to add a level of protection against automated bots. When creating a form handler, the field insightly_additional_field can be added in the Form Field Mapping section; when the form HTML is generated, it will appear similar to the below:

<label for="insightly_additional_field">Comments</label>

</div>

Tracking Events

Insightly Marketing users can track Prospect form interactions on landing pages created with Insightly Marketing or on a preexisting form on their own website (after connecting a form handler to the form). Form interactions can be reviewed via the Prospect's record on the Timeline tab. Insightly will record information that a Prospect entered on a form; these events will be recorded even if the Prospect does not submit a form. However, there are no events recorded that specify when a Prospect has made changes to the form.

When a visitor interacts with a form, Insightly will record one event in the visitor activity table for all the form fill events for that interaction, for that specific visitor session. When the timeline entry is clicked, information about how far the Prospect reached in the form fill will appear. If a visitor interacts with a form, Insightly will capture the following:

The form submission ID
The visitor ID
The Prospect ID
The date of submission
The database action
The method
The HTTP response code
The user IP address
The user agent
The referrer
Form data that was entered, such as email address, last name, etc.

Enable Auto Filling Geographic Prospect Data

Insightly can automatically fill the country, state, and Canadian province in a Prospect record based on the GeoIP information from a form submission.

To enable the autofill of geographic Prospect data within Insightly Marketing, click the user profile in the upper right corner and select System Settings. Under the Feature Settings section, select Form Features.
1. Enable the checkbox Auto-Populate Prospect Address.

Create a Form Handler

Navigate to Forms via the objects on the left side of Insightly Marketing.

From the forms list view, click the New Form Handler button in the upper right.

The Add New Form Handler popup will appear where details for the form handler can be entered in the Form Handler Information section:

Field	Information
Name	Required Field. Enter a unique name for the form handler
Folder	It is a best practice to efficiently organize form handlers into folders so they can be easily located at a later date
Success Page	Select from the drop-down menu a success page. If Specific URL is chosen, a URL will be required to be entered.
Error Page	Select from the drop-down menu an error page. If Specific URL is chosen, a URL will be required to be entered.
Duplicate Handling	Define how to handle duplicates - by default, this is set to update existing Insightly Marketing records rather than creating new ones when a duplicate is received.
Email Address Validation	Define the validation rule for email addresses entered on the form.
Recaptcha Enabled	To allow reCAPTCHA for the form handler, enable this checkbox

The FormFieldMapping section is used for creating fields for the form handler or for mapping fields from an existing form to the form handler being created. The Email field is the only required field for a form; Add Form Field can be clicked to add additional fields and define them as optional or required (spaces are not allowed in the FieldName value).
- When mapping fields from an existing form, ensure that the Field Name value matches the field's name within the coding of the existing form. It is required to match the "name" property value of that corresponding element on the existing form exactly.
Via the Permissions section, define the visibility of the form handler.
When all details have been applied, either of the following can be clicked as applicable:
- Save & New: Save the new form handler and reload the AddNewFormHandler popup to create another new form handler.
- Save: Save the new form handler and close the Add New Form Handler popup.

Generate an HTML version of Form Handler

Insightly Marketing users can generate an HTML version of form from a Form Handler record. This code can then be added to a website and will contain all fields from the form handler, in the same order. This functionality is useful for users that require additional customization abilities for their form. Once a form is generated into HTML, a developer can customize not only the design, but can also add external elements that may not be directly related to Insightly.

To general an HTML version of a form handler, navigate to Forms via the objects on the left side of Insightly Marketing.
Via the list view of form handlers, locate and open the record for the applicable form handler.
1. From within the form handler's record, click the Actions button in the upper right corner and select Generate Form HTML.
2. HTML version of the form will display in a popup where it can be copied and added to the applicable website.

Validation Errors

It includes the validation errors for the following scenarios:

Form field related validation error
Validation error from the custom validation rules defined
Recaptcha errors
Invalid content type
Form handler not found
Form data not found
User data not found
Invalid input characters
Invalid form hash
Exceeded Submission limit (if 5 or more form submissions in a 5 minute window)
Permission Denied (if the instance no longer has an active marketing subscription)

Form Handler Actions

When editing, cloning, changing the record owner, or deleting a form handler, these actions can be done via two different routes:

Route 1: Via the list view of form handlers, the three dots menu on the far right of a form handler can be clicked and the applicable function can be chosen from the expanded list.

Route 2: Via the list view of form handlers, a form handler record can be opened. Once opened, the Actions drop-down in the upper right corner can be clicked and the applicable function can be chosen from the drop-down list.

Edit a Form Handler

To edit a form handler, navigate to Forms via the objects on the left side of Insightly Marketing.
From the list view of form handlers, locate the form handler that requires editing.
1. Click either the three dots menu to the far right of the form handler in the list view or click the Actions button in the upper right of the form handler record. From the available options, select Edit this Form Handler.
  - Finish actions for a form handler can be edited by opening the form handler record and selecting the FinishActions tab. Locate the finish action the requires editing and click the three dots menu on the far right of the finish action and select Edit This Finish Action.

Clone a Form Handler

To clone a form handler, navigate to Forms via the objects on the left side of Insightly Marketing.
From the list view of form handlers, locate the form handler that requires cloning.
1. Click either the three dots menu to the far right of the form handler in the list view or click the Actions button in the upper right of the form handler record. From the available options, select Clonethis Form Handler.

Change the Form Record Owner

To change the record owner of a form handler, navigate to Forms via the objects on the left side of Insightly Marketing.
From the list view of form handlers, locate the form handler that requires a new record owner.
1. Click either the three dots menu to the far right of the form handler in the list view or click the Actions button in the upper right of the form handler record. From the available options, select Change Record Owner.

Delete a Form Handler

To delete a form handler, navigate to Forms via the objects on the left side of Insightly Marketing.
From the list view of form handlers, locate the form handler that requires deletion.
1. Click either the three dots menu to the far right of the form handler in the list view or click the Actions button in the upper right of the form handler record. From the available options, select Deletethis Form Handler.
  - Finish actions for a form handler can be deleted by opening the form handler record and selecting the FinishActions tab. Locate the finish action the requires deletion and click the three dots menu on the far right of the finish action and select DeleteThis Finish Action.

Add Finish Actions to a Form Handler

Finish actions allow users to add automated activity that is triggered when someone submits a form. For example, if users should be notified when a form has been submitted, a finish action can be added to the form record that is triggered when the form has been completed and an email can be sent to any users/stakeholders to notify them of the form submission.

Finish actions will typically occur immediately after a form has been submitted and cannot be scheduled for a later date or time. They can however be assigned conditional criteria that will not allow the action to occur unless the submitted form has met the criteria that has been set.

If multiple finish actions have been added, they will only execute based on the Prospect's original field values. For example, if a Prospect started with a score of five and it was updated to ten as a request of the first action taken. If a finish action were to execute for Prospects with a score of ten or more, it would not execute because the score was originally five.

Finish actions will not execute if Insightly cannot identify the Prospect who completed the form. The Prospect needs to have filled out and submitted a form with the email address associated with their Prospect record.

To add finish actions to a form, navigate to Forms via the objects on the left side of Insightly Marketing.
Locate and open the record of the form handler that requires finish actions.
1. Select the FinishAction tab and click Add Finish Action.
  1. From the expanded list, select the applicable finish action to add to the form handler.
  2. A popup window will appear with fields to complete to create the finish action. Enter the required fields (and the optional ones as desired). Conditional criteria can be added to define the criteria for the finish action to apply. For example, the Send Email finish action could require that the employee count needs to be greater than ten for the action to be triggered.
  3. When the finish action fields have been completed, click Save Finish Action to add it to the form handler.
    - If multiple finish actions have been added to a form handler, the order of the actions can be adjusted by clicking the three dots menu to the far right of each finish action and selecting Move Up in Order or Move Down in Order as applicable:

Connect Preexisting Form to a Form Handler

Once a form handler has been created, it can be connected to an existing form to provide tracking information for the form. Via the Submissions tab of a form handler record, users can review the Prospects who have filled out the form.

Navigate to Forms via the objects on the left side of Insightly Marketing.
From the list view of form handlers, locate and open the record for the form handler to connect to the preexisting form.
1. Within the form handler record, copy the Form Submit URL and add it to the API POST request of the preexisting form.
  - Insightly form handlers will only accept POST form submissions; "multipart/form data" posts will not be accepted due to the fact that form handlers do not support file uploads.

Generate an HTML Version of a Form Handler

Insightly Marketing users can generate an HTML form from a form handler record; this code can then be added to a website and will contain all fields from the form handler, in the same order. This functionality is useful for users that require additional customization abilities for their form. Once a form is generated into HTML, a developer can customize not only the design but can also add external elements that mat not be directly related to Insightly.

To general an HTML version of a form handler, navigate to Forms via the objects on the left side of Insightly Marketing.
Via the list view of form handlers, locate and open the record for the applicable form handler.
1. From within the form handler's record, click the Actions button in the upper right corner and select Generate Form HTML.
2. The form HTML will display in a popup where it can be copied and added to the applicable website.

Was this article helpful?