Form Listening

Form Listening allows you to set a value for a property in a visitor's profile based on visitor input. You can use the interaction to both set the value of an existing profile property to a particular value as well as add a value to a profile property that supports multiple values. The input from the visitor is derived from a form submitted on a web page.

In this listener you define which form field contains the data to be written to the profile property, the profile property that is written to and the circumstance that triggers the submission of the data to the profile property.


Form Listening configuration

Follow the steps in the following sections to configure Form Listening.

Defining listen rules

A listen rule defines the form field from which the text or value is taken, the profile property to which the text or value is added or set, and the event that triggers the setting or adding of the text or value to the profile property. The text or value can also be converted according to a defined mapping before it is written to the visitor profile.

  • If you set the value of a profile property, the current text or value is replaced by the new text or value. An option to set "only if empty" exists to ensure that only the first occurrence of a value is stored in the specified profile property.
  • If you add the text or value to a profile property, the profile property will contain multiple entries. You must create a listen rule for each form field that you want to write to a profile property.

There are three different types of listen rules that you can create. They differ in the circumstance that triggers the submission of the data in a form field to a profile property. The three different listen rule variations are:

Write data to a profile property when the surrounding form is submitted
Write data to a profile property when a custom form is submitted
Write data to a profile property when a custom position is clicked

Note: The permission level of the website visitor and the profile property must be sufficient to allow the text or value to be written to it. For example, if the permission level of the profile property is Level 2 and the visitor has selected Level 1 permission, the text or value will not be written to the profile property.

Write data to a profile property when the surrounding form is submitted

This listen rule is triggered when an entire form is submitted. The data from the form field you specify is written to the profile property you specify.

    1. Click [Add Rule].
    2. Select whether this rule is an add or set operation. An add operation keeps the existing data in the profile property and adds the new data to it. A set operation substitutes the existing data with the newly submitted data, unless the "only if empty" option is checked.
    3. Select whether this rule deals with text or a value.
    4. Click the "define form field" link. This is the form field from which you want to take the data that is written to the profile property.
      • Enter a name for the form field in the "Name" text box. This is an internal name for the form field that you choose to use identify it — it is not the name of the form field in the source code.
      • Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: http://api.jquery.com/category/selectors/.
      • To define the area using the Visual Picker, click Visual Picker.
      • Click OK.

 

  1. Click the "define profile property" link. See Profile properties for complete information on working with profile properties.
  2. If you want to convert the value, click here for complete information on configuring value conversion.
  3. Repeat the steps above for each listen rule of this type you want to create.
  4. Click [Save].

Write data to a profile property when a custom form is submitted

This listen rule is triggered when a specified form is submitted. Typically this option is used when you want to write data from a form field to a profile property when a specific form is submitted, not necessarily the one containing the form field in question.

    1. Click [Add Rule].
    2. Select whether this rule is an add or set operation. An add operation keeps the existing data in the profile property and adds the new data to it. A set operation substitutes the existing data with the newly submitted data, unless the "only if empty" option is checked.
    3. Select whether this rule deals with text or a value.
    4. Click the "define form field" link. This is the form field from which you want to take the data that is written to the profile property.
      • Enter a name for the form field in the "Name" text box. This is an internal name for the form field that you choose to use identify it — it is not the name of the form field in the source code.
      • Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: http://api.jquery.com/category/selectors/.
      • To define the form field using the Visual Picker, click Visual Picker.
      • Click OK.

 

  1. Click the "define profile property" link. See Profile properties for complete information on working with profile properties.
  2. Click the "the surrounding form is submitted" link.
  3. Select "Custom defined form is submitted".
  4. Enter a name for the custom defined form in the "Name" text box.
  5. Enter a valid jQuery Selector to define the custom defined form in the "Selector" text field. For complete information on jQuery Selectors, follow this link: http://api.jquery.com/category/selectors/.
  6. To define the form using the Visual Picker, click Visual Picker.
  7. Click [OK].
  8. If you want to convert the value, click here for complete information on configuring value conversion.
  9. Repeat the steps above for each listen rule of this type you want to create.
  10. Click [Save].

Write data to a profile property when a custom position is clicked

This listen rule is triggered when a custom position is clicked in by the website visitor. The data from the form field you specify is written to the profile property you specify.

    1. Click [Add Rule].
    2. Select whether this rule is an add or set operation. An add operation keeps the existing data in the profile property and adds the new data to it. A set operation substitutes the existing data with the newly submitted data, unless the "only if empty" option is checked.
    3. Select whether this rule deals with text or a value.
    4. Click the "define form field" link. This is the form field from which you want to take the data that is written to the profile property.
      • Enter a name for the form field in the "Name" text box. This is an internal name for the form field that you choose to use identify it — it is not the name of the form field in the source code.
      • Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: http://api.jquery.com/category/selectors/.
      • To define the form field using the Visual Picker, click Visual Picker.
      • Click OK.

 

  1. Click the "define profile property" link. See Profile properties for complete information on working with profile properties.
  2. Click the "the surrounding form is submitted" link.
  3. Select "Custom position is clicked".
  4. Enter a name for the custom position in the "Name" text box.
  5. Enter a valid jQuery Selector to define the custom position in the "Selector" text field. For complete information on jQuery Selectors, follow this link: http://api.jquery.com/category/selectors/.
  6. To define the position using the Visual Picker, click Visual Picker.
  7. Click [OK].
  8. If you want to convert the value, click here for complete information on configuring value conversion.
  9. Repeat the steps above for each listen rule of this type you want to create.
  10. Click [Save].

Converting values

Before committing text or a value to a profile property, you can convert it based on a defined mapping. You might want to do this in cases where you want to write a different value to a profile property than what was taken from the form field. For example, if a drop-down list in a form has two choices, "Male" and "Female", but you want to write "M" or "F" to the profile property, you can create a value conversion mapping to do this.

To convert text or a value based on a mapping, follow these steps:

  1. Click the "do not convert the value" link.
  2. Select "Convert based on mapping".
  3. In the "Original value" text field, enter the text or value from the form field that you want to convert.
  4. In the "Converted value" text field, enter the text or value that you want to convert the original text or value to.
  5. Click [Save mapping].
  6. Repeat the steps above for each mapping that you want to define.
  7. Click [OK].

To delete a mapping, click the delete icon to the right of the mapping.


Copying and deleting rules

Click here for information on copying and deleting rules in BlueConic.

 

The Form Listener is a standard plugin.