Loading...

RECOMMENDATION: If you are using a version of The Portal Connector higher than 4.0, we strongly recommend utilizing the MVC based widgets and components to create your site. This documentation is for legacy purposes only and will soon be deprecated.

CRM Validator

Properties API Related
Widget Type:
Form Widgets
TPC Version:
  • 3.3 +
validatorlogo
The CRM Validator widget allows you to validate the number of records retrieved from a user-defined Fetch XML. In the event of a failed validation, the widget will display a user-defined message and prevents the form from being submitted.

For example: The CRM Validator can be used to prevent duplicate emails from being submitted. To do this you would set a fetch to look for all Account Emails while also adding a filter to the fetch. Then, you would navigate to the Filter tab. In this tab, you may make use of the unique Field Value Type in order to retrieve the correct value from the form to validate it with already existing records.

Configuration

Basic Setup 


In order to configure the widget you must do the following:

  1. From the Portal Connector widget list click and drag the CRM Validator into the body of your form.

  2. In order for the widget to function properly it must be configured. Click on the edit button to display the properties prompt. It should look like this:

    CRM Validator Properties

  3. Please note that the configuration above will show a message if the Fetch XML returns greater than or equal to one matching record. It is very important to ensure that the fields that you wish to validate have an alias set so that you may compare the field data to any existing records. 

Filters 

CRM Validator Filter Properties

  1. Displayed here, the CRM Validator filter tab has a unique type known as the Field Value. You may also click on the Value box to show a drop down list of widgets present on the form. This means that the CRM Validator will filter your records by the value in the specified field during a submission attempt. Once you have finished configuring the filter tab, click on the save button to save the widget. 

Example 

Here is an example of the validator in action. To start, a CRM Validator is configured to fetch all Accounts that have the same email address as provided in the email address textbox. Should the system find at least one account with this same email address, you will not be allowed to submit the form:

CRM Validator Properties

CRM Validator Example

Widget Properties

Basic Properties

Aggregate Fetch

The Aggregate Fetch checkbox will determine whether the fetch you are using to validate the form will be aggregated or not. When checked, you will be provided with a Aggregate Field Alias textbox which the validator will use to validate the fetched results with your form submission. For example, say an Account is only allowed to have five active cases at any given time. You could fetch the count of cases for a particular account and not allow anyone to make a new case record should the returned number of cases be greater than five.

Aggregate Field Alias

The Aggregate Field Alias textbox will fetch an aggregated attribute by its alias in order to validate a form submission.

Message

The Message textbox allows you to set a message for the CRM Validator to return in the event of a failed validation.

Operator

The Operator drop down list allows you to choose an operator from which to compare a value with. Applicable options include: Equal to, Less Than, Less Than or Equal To, Greater Than, and Greater Than or Equal to.

Number of Records

The Number of Records numeral text box allows you to set a whole, positive number for CRM Validator widget to compare with its results.

Fetch XML

The FetchXML text area determines what sort of data a widget will be populated with. 

Clicking the Load Default Fetch option will populate the FetchXML area with a default fetch based on the CRM Entity chosen. By clicking the Build button, we will be sent to another page in order to determine what the widget will look up. For more information on how to use the FetchXML function.

Validate On Edit

The Validate on Edit advanced property will determine whether the CRM Validator will attempt to run its validation when the form is in edit mode. By default, this is set to true.

Validate on Load

The Validate on Load advanced property will allow the CRM Validator to activate when the form is loading. If the form is in edit mode, this is when all of the values on the form have been populated. If the form is in add mode, you cannot filter by field values.

Show Message on Error

The Show Message on Error advanced property will allow you to control if the error message will be shown if the validation fails.

Advanced Properties

Advanced properties provide additional functionality. They can be accessed by clicking on the "Advanced" Button in the bottom right corner of the widget designer.

Aggregate Fetch

The Aggregate Fetch checkbox will determine whether the fetch you are using to validate the form will be aggregated or not. When checked, you will be provided with a Aggregate Field Alias textbox which the validator will use to validate the fetched results with your form submission. For example, say an Account is only allowed to have five active cases at any given time. You could fetch the count of cases for a particular account and not allow anyone to make a new case record should the returned number of cases be greater than five.

Aggregate Field Alias

The Aggregate Field Alias textbox will fetch an aggregated attribute by its alias in order to validate a form submission.

Message

The Message textbox allows you to set a message for the CRM Validator to return in the event of a failed validation.

Operator

The Operator drop down list allows you to choose an operator from which to compare a value with. Applicable options include: Equal to, Less Than, Less Than or Equal To, Greater Than, and Greater Than or Equal to.

Number of Records

The Number of Records numeral text box allows you to set a whole, positive number for CRM Validator widget to compare with its results.

Fetch XML

The FetchXML text area determines what sort of data a widget will be populated with. 

Clicking the Load Default Fetch option will populate the FetchXML area with a default fetch based on the CRM Entity chosen. By clicking the Build button, we will be sent to another page in order to determine what the widget will look up. For more information on how to use the FetchXML function.

Validate On Edit

The Validate on Edit advanced property will determine whether the CRM Validator will attempt to run its validation when the form is in edit mode. By default, this is set to true.

Validate on Load

The Validate on Load advanced property will allow the CRM Validator to activate when the form is loading. If the form is in edit mode, this is when all of the values on the form have been populated. If the form is in add mode, you cannot filter by field values.

Show Message on Error

The Show Message on Error advanced property will allow you to control if the error message will be shown if the validation fails.

API

get_validationMessage()

Returns the validation message from the widget. 

Returns

String

get_isValid()

Returns true if the set validation passes on the specified field. 

Returns

Boolean

get_recordArray()

Returns an array populated with the records that activate the validator. 

Returns

Array

get_recordCount()

Returns the number of records that have activated the validator. 

Returns

Number

get_dataFieldName()

Returns the developer name for the control. 

Returns

String

get_value()

Returns true if the current form is valid for submission.

Returns

Boolean

Full API With Examples

How to's

Related examples of CRM Validator Configuration