Help Center

With rule-based form listening in BlueConic, you can set a value for a property in a visitor's profile based on visitor input. You can use the interaction both to set the value of an existing profile property to a particular value and also to 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 it is written to, and the circumstance that triggers the submission of the data to the profile property.

---

Configuring a Rule Based Form Listener

Follow the steps in the following sections to configure form listening.

1. Open the Listeners page and click Add listener.
   
2. Choose Rule Based Form Listener and enter a name for the listener.
3. In the Where field, define the channels and optionally the URLs where the listener will be active.
4. Click Add rule to define the listening rule(s).
   

Defining listener 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 addition of the text or value to the profile property:

• Value: Used for input elements.

• Text: Used for other text elements, such as titles or paragraphs.

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.

Listening rules: You can create several types of listening rules. They differ in the circumstance that triggers the submission of the data in a form field to a profile property. The 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 form field value changes
• Write data to a profile property when a custom form is submitted
• Write data to a profile property when a custom position is clicked
• Write data to a profile property when a location hash changes

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.

---

Writing data to a profile property when a 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. (Note: This option is currently available for web channels, but not for native app channels.)

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.

For this form field, complete these steps:

1. 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.
2. Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
3. To define the area using the Visual Picker, click Visual Picker.
4. Click OK.
5. Click the "define profile property" link. You can use an existing profile property or enter a new profile property name to create a new one here. See Profile properties for complete information on working with profile properties.
6. If you want to convert the value, see the instructions in "Converting values" below for complete information on configuring value conversion.
7. Repeat the steps above for each listen rule of this type you want to create.
8. Click Save.

---

Writing data to a profile property when a form field value changes

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.

For this form field complete these steps:

1. 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.
2. Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
3. To define the form field using the Visual Picker, click Visual Picker.
4. Click OK.
5. Click the "define profile property" link. You can use an existing profile property or enter a new profile property name to create a new one here. See Profile properties for complete information on working with profile properties.
6. Select the option "form field value changes" to store the form data when it changes.
7. If you want to convert the value, see the instructions in "Converting values" below for complete information on configuring value conversion.
8. Repeat the steps above for each listen rule of this type you want to create.
9. Click Save.

---

Writing 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.

For this form field, complete these steps:

1. 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.
2. Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
3. To define the form field using the Visual Picker, click Visual Picker.
4. Click OK.
5. Click the "define profile property" link. You can use an existing profile property or enter a new profile property name to create a new one here. See Profile properties for complete information on working with profile properties.
6. Click the "the surrounding form is submitted" link.
7. Select "Custom defined form is submitted".
8. Enter a name for the custom defined form in the "Name" text box.
9. 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: https://api.jquery.com/category/selectors/
10. To define the form using the Visual Picker, click Visual Picker.
11. Click OK.
12. If you want to convert the value, see the instructions in "Converting values" below for complete information on configuring value conversion.
13. Repeat the steps above for each listen rule of this type you want to create.
14. Click Save.

---

Writing 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.

For this form field, complete these steps:

1. 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.
2. Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
3. To define the form field using the Visual Picker, click Visual Picker.
4. Click OK.
5. Click the "define profile property" link. You can use an existing profile property or enter a new profile property name to create a new one here. See Profile properties for complete information on working with profile properties.
6. Click the "the surrounding form is submitted" link.
7. Select "Custom position is clicked".
8. Enter a name for the custom position in the "Name" text box.
9. Enter a valid jQuery Selector to define the custom position in the "Selector" text field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
10. To define the position using the Visual Picker, click Visual Picker.
11. Click OK.
12. If you want to convert the value, see the instructions in "Converting values" below for complete information on configuring value conversion.
13. Repeat the steps above for each listen rule of this type you want to create.
14. Click Save.

---

Writing data to a profile property when a location hash changes

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.

For this form field, complete these steps:

1. 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.
2. Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
3. To define the form field using the Visual Picker, click Visual Picker.
4. Click OK.
5. Click the "define profile property" link. You can use an existing profile property or enter a new profile property name to create a new one here. See Profile properties for complete information on working with profile properties.
6. Select the option "Location hash name" to execute the listener rule whenever the hash part of the location or URL changes to a value you specify in the Location hash name field.
7. Click OK.
8. Choose whether to convert the value. If you want to convert the value, see the instructions in "Converting values" below 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. 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 you want to convert.
   4. In the "Converted value" text field, enter the text or value 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.

---

Privacy management

Listeners can be added to Objectives, allowing for privacy management of the information that is being picked up. The listener will only update a profile if the visitor consented to at least one of the objectives that it is linked to.

---

Copying and deleting rules

Learn more about copying and deleting rules in BlueConic.