Custom Fields

• Table of Contents
• Overview
• Properties Common to Most Custom Fields
  • Name
  • Required
  • Instructions
  • Default Value
• Custom Field Types
  • Text
  • Text Multiline
  • Number
  • Date
  • Select Single Dropdown
  • Select Single Radio
  • Select Multiple Checkboxes
  • Boolean
• Custom Field Interpolation Options
• Adding Custom Fields to a List That Already Has Subscribers
• Editing Field Requirements
• Editing Options on Select Field Types
• Different Mailing Lists With the Same Custom Fields
• Global Custom Fields

Overview

GreenArrow Studio allows you to add custom fields to a mailing list, so that you can associate additional information with each subscriber record beyond the base information already included in the subscriber record. Each subscriber on the mailing list can store a value for each custom field.

For example, custom fields might be First Name or CustomerID.

Each mailing list maintains its own set of custom fields which are independent from any other mailing list.

Global custom fields are also available. They apply to all mailing lists within an organization.

Properties Common to Most Custom Fields

Name

(Valid for all custom field types)

The name that describes this custom field. The name will appear wherever the custom field is referenced. For example, Name or Favorite Color.

The following requirements are applied to custom field names:

• The name must be less than 50 characters.
• A mailing list can not have two custom fields with the same name.
• The name cannot be the same as a built-in field.
• The name cannot begin with the word “Data” (all such names are reserved for future built-in fields).

Required

(Valid for all custom field types).

This states that a value is required.

For each field type, this means specifically:

Field type	Behavior
Text	A blank string, or string only containing whitespace is not allowed.
Text Multiline	A blank string, or string only containing whitespace is not allowed.
Number	A number must be specified.
Date	A date must be specified.
Select Single Dropdown	One option must be selected.
Select Single Radio	One option must be selected.
Select Multiple Checkboxes	At least one option must be checked.
Boolean	True or False must be selected, and blank values are not allowed.

This requirement is enforced when editing or adding a subscriber through the UI and through an import.

You may want to create a default value for custom fields that are required. If a required field does not have a default value, then a value must be manually specified for that field.

If you enable the required option for a custom field on a list that already has subscribers, then you may have subscribers which don’t have any value. If/when you edit these subscribers, you then must supply a value for the required custom fields, because the subscriber will not validate without the a value for the required custom field.

Instructions

Each custom field’s Instructions setting is used to control the text that’s displayed below the custom field when adding or editing subscriber. This field may be left blank if the custom field has no instructions.

You can toggle instructions on and off by clicking the Quick Tips button:

Default Value

Valid for only these types of custom fields:

• Text
• Text Multiline
• Number
• Boolean

The default value is used as the default for any new subscribers. Specifically:

• If you manually add a subscriber through the UI, the form will be pre-populated with this default value.

• If you add a subscriber using the import feature and do not associate a column with this custom field or hard-code a value to this custom field, then the default value will be used.

What this setting does not do:

• If you add a subscriber through the UI or the import feature and specify a blank value for this custom field, a blank value will be stored (or for a Boolean custom field, False will be stored). The default value will NOT be used.

• Adding a default value to a custom field or creating a new custom field with a default value, does NOT affect the value for any subscribers already in the list, even if they don’t have a value for this custom field.

Custom Field Types

There are many types of custom fields to support different types of data.

Text

Allows a single line of text to be entered.

Field Parameters:

• Default value - See this page’s Default Value section.

• Minimum length - The minimum length in characters for any non-blank values. Leave blank to have no requirement.

• Maximum length - The maximum length in characters for any non-blank values. Leave blank to have no requirement.

• Interpolation - Allows you to specify how the field value will be replaced in the content or click URL. By default, content will be HTML encoded in HTML emails or URL encoded in click URLs. See the section of this document called “Custom Field Interpolation Options” below for more information.

Misc details:

• Accepts UTF-8 text.

• Maximum amount of data supported: 1,024 characters

• Leading and trailing whitespaces are not stripped.

Text Multiline

Allows multiple lines of text to be entered with a multi-line text box.

Field Parameters:

• Default value - See this page’s “Default Value” section.

• Number of rows - The number of lines tall to make the editing box when presenting this field in a form. Defaults to 5 if blank. Valid values are 1-100. This does not limit the amount of data that may be entered.

• Interpolation - Allows you to specify how the field value will be replaced in the content or click URL. By default, content will be HTML encoded in HTML emails or URL encoded in click URLs. See the section of this document called “Custom Field Interpolation Options” below for more information.

Misc details:

• Accepts UTF-8 text.

• Maximum amount of data supported: 10,240 characters

• Leading and trailing whitespaces are not stripped.

Number

Allows an integer number.

Field Parameters:

• Default value - See this page’s “Default Value” section.

• Minimum value - The minimum integer value required when this field is not blank. Leave this blank to have no requirement.

• Maximum value - The minimum integer value required when this field is not blank. Leave this blank to have no requirement.

• Supports decimals - Controls whether or not subscribers should be allowed to have decimal values for this field value. Once enabled, this field cannot be disabled.

Misc details:

• Integers may only be entered as follows: an optional hyphen (-) followed by one or more digits. Scientific notation, hex, octal, or binary formats are not supported. Leading and trailing whitespace is stripped.

• Decimal values, such as 12.3, are not supported by this type.

• Range of valid values: -2,147,483,648 to 2,147,483,647(signed 32-bit integers).

Date

Allows a date to be entered. A date consists of a valid year, month, and day.

Field Parameters:

• Display order - The order to display year, month and date to the user.

Misc details:

• Dates must appear on the Gregorian calendar to be valid. For example: February 29th 2011 is not a valid date.

• Range of valid values: January 1, 1700 to December 31, 3000.

• Uses Gregorian calendar for all dates.

Select Single Dropdown

Allows zero or one of several pre-defined options to be selected.

Shows the options to the user using a drop-down box.

Field Parameters:

• Select options - A list of the different options and the order they will be presented to the user.

Select Single Radio

Allows one or more options to be selected. Shows the options to the user using radio buttons.

Field Parameters:

• Select options - A list of the different options and the order they will be presented to the user.

Misc details:

• It is possible for zero options to be selected. This can happen in two ways: (1) a blank text value is imported into this custom field, or (2) this custom field is added to a list that already has subscribers, each already-existing subscriber will have no options selected for this custom field.

Select Multiple Checkboxes

Allows zero or more options to be selected. Shows the options to the user with a checkbox for each option.

Field Parameters:

• Select options - A list of the different options and the order they will be presented to the user.

Misc details:

• It is possible for zero options to be selected by un-checking all of the checkboxes.

Boolean

Allows a true or false value to be selected.

Field Parameters:

• Default value - See this page’s Default Value section.

Custom Field Interpolation Options

The “Text” and “Text Multiline” custom field types provide “Interpolation” options. These allow you to define how the field will be interpolated into the document (i.e. whether or not it will be HTML or URI encoded).

Be careful when using raw custom field interpolation. You are responsible for HTML entity encoding and/or URI encoding. Additionally, when a raw custom field is used in a link the resulting URL may depend on if click tracking is used with the email.

If click tracking is used, then the raw bytes of the custom field value are inserted into the URL in the Location header returned to the client. The raw bytes never go through a HTML context, and thus any HTML entities present (for example &) will not be decoded.

If click tracking is not used, the raw bytes of the custom field value are inserted into the HTML href attribute. The browser will interpret any HTML entities present. Additionally, if the href attribute value is enclosed in double or single quotation marks, a non-HTML-entity-escaped double or single quotation mark can prematurely end the href attribute value.

Adding Custom Fields to a List That Already Has Subscribers

If you add a custom field to a list that already has subscribers, then subscribers already in the database will get the following value for the newly created custom field:

Field type	Value
Text	A blank string
Text Multiline	A blank string
Number	A blank value
Date	A blank value
Select Single Dropdown	No options will be selected
Select Single Radio	No options will be selected
Select Multiple Checkboxes	No options will be selected
Boolean	False

Editing Field Requirements

It is possible for subscriber data in the database to not meet the current validation requirements of the custom fields.

This can happen if:

• You set a field to be required where subscribers already have blank values for it.

• You change the minimum length or maximum length parameters for a text field.

• You change the maximum value or minimum value parameters for a number custom field.

• You remove options from a select custom field that is required and there were subscribers who had only this option selected.

A subscriber being in the database with invalid data has interesting effects:

• If you edit a subscriber, make no changes, and try to save the form, the save will fail.

• If you do an import and try to update one column with valid data, the import can fail on that subscriber because a different column that you didn’t attempt to update had invalid data.

We recommend that you avoid creating subscribers with invalid data. Think very carefully before your tighten validation requirements on existing custom fields.

Editing Options on Select Field Types

If you rename an option, all subscribers that had that option selected with the old name will have it selected with the new name.

If you remove an option on a select-type field, then all subscribers which have this option selected will no longer have this option selected. If you then create a new option with that same name, none of those subscribers who had the old option with that name selected will have the new option with that name selected.

If you add an option, no already existing subscribers will have this option selected.

Different Mailing Lists With the Same Custom Fields

Each mailing list has its own custom fields which are separate from any other mailing list.

This means that if you have a First Name field on Mailing list #1 and a First Name field on Mailing list #2, and you update the field on Mailing list #1 the changes are not automatically applied to the First Name field on Mailing list #2. The two custom fields are completely different objects in the database, even though they have the same name.

However, we know that sometimes you want multiple mailing lists to have the same custom fields. Global custom fields are how you can accomplish this.

Global Custom Fields

Global custom fields apply to all mailing lists within an organization. They do not apply to mailing lists in other organizations.

Global custom fields are managed in “Admin” => “My Organization” => “Global Custom Fields”.