Configuration API: Adding and Updating Fields

Common Field Attributes

All fields share a set of common attributes:

  • type - required

The type of field that you wish to create or update. Currently supported field types are:

  • checkbox
  • dateselect
  • email
  • password
  • radio
  • select
  • text
  • textarea

Click on one of the types for a full example of a field definition.

  • name - required

A unique name used to identify the field (cannot contain spaces).

Example:


"name": "myCoolField"

  • schemaAttribute - required

A path to the schema attribute in the profile record to which this field's value should be mapped. 

Example:


"schemaAttribute": "primaryAddress.phone"

  • label - optional

An optional field label used by the Janrain Registration widget. It is not necessary for pure API implementations. It must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers.

Example:


"label": {
  "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
}

  • tip - optional

An optional field tooltip that is used by the Janrain Registration widget. It is not necessary for pure API implementations. It must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers.

Example:


"tip": {
  "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
}

  • validation - optional

An optional list of validations that should be applied to this field. Validations have the following attributes:

  • rule - required

The name of the validation rule to apply. Must be one of the validations allowed for this field's type. 

  • value - required

The value to use for validation. For some validations this will just be true or false (for example, required). For others this will be a configuration value for the validation. 

  • message - required

The error message to be used if the validation fails. This must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers.

Note. Message is not supported by the matchOptions validation, but is required for all others.

Example:


"validation": [
  {
    "rule": "required",
    "value": "true",
    "message": {
      "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
    }
  }
]

Type-specific Field Attributes

Each type of field has additional parameters specific to it. Refer to the table at the end of this section to see which attributes apply to which fields.

  • socialProfileData - optional

When a user logs in using a social provider, Janrain's Social Login service returns the social provider in the form of a Portable Contact payload. You can use the socialProfileData attribute to specify which data from the social profile should be used to populate the value for this field in the Janrain user record.

Example:


"socialProfileData": "profile.name.familyName"

  • placeholder - optional

This is used as the placeholder attribute on form elements when using the Janrain widget. This must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers.

Example:


"placeholder": {
  "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
}

  • preChecked - optional

This only applies to the checkbox field type. If set to true, the checkbox will appear pre-checked to new users registering with the Janrain widget. This is useful if you want to require that users specifically opt out of something (for example, a newsletter).

Example:


"preChecked":true

  • submitValue - optional

This only applies to the checkbox field type. Use this if you need to specify the submit value of a check box (that is, the check box should submit a value other than "on").

Example:


"submitValue": "true"

  • options - required

For the radio and select fields, you must define the options to be displayed. Options have the following attributes:

  • disabled - optional

Set this to true to disable the option.

  • label - required

The label to display for this option. This must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers.

  • selected - optional

Set this to true to select this option by default. Only one option in a field can have this attribute.

  • value - required

The value of this option.

Example:


"options": [
  {
    "selected": true,
    "label": {
      "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
    },
    "value": "waffles"
  }
]

Attribute

text

email

password

checkbox

radio

select

textarea

socialProfileData

yes

yes

-

-

-

-

yes

placeholder

yes

yes

yes

-

-

-

yes

preChecked

-

-

-

yes

-

-

-

submitValue

-

-

-

yes

-

-

-

options

-

-

-

-

yes

yes

-

Validations

Each field supports a subset of the validations available. Refer to the table at the end of this section to determine which validations are available to you.

  • blacklist - Takes a list of disallowed strings as its value.

Example:


{
  "rule": "blacklist",
  "value": ["do not allow this","or_this!"],
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

  • format - Asserts that the field conforms to a certain format. It takes one of the following predefined formats as its value:

Example:


{
  "rule": "format",
  "value": "email",
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

  • alpha - Only allows alphabetic characters, and must contain at least one character. Defined as /^[a-z]+$/i.
  • alphaExtended - Only allows alphabetic characters, dashes (-), and single quotes('). The field value must contain at least one character. Defined as /^[a-zA-Z\-']+$/.
  • alphaExtendedSpaces - Only allows alphabetic characters, dashes (-), single quotes('), and whitespace characters (\r, \n, \t, and \f). Defined as /^[a-zA-Z\-'\s]+$/.
  • alphaNumeric - Only allows alphabetic and numeric characters. The field value must contain at least one character. Defined as /^[a-z0-9]+$/i.
  • alphaNumericExtended - Only allows alphabetic and numeric characters. Allows for dashes (-), underscores (_), and periods (.) within the value, so long as they are not at the beginning or the end. The field value must contain at least three characters. Defined as /^[a-z][-a-z0-9\s_.]*[a-z0-9]$/i.
  • email - Only allows valid email addresses. Defined as /^.+@(?:[^.]+\.)+(?:[^.]{2,})$/.
  • i18nAlphaNumeric - Allows only alphanumeric characters without excluding characters containing accents (for example, é). Defined as /^[^-\s^`~!@#$%^&*()_=+\[{\]}\|;:‘“,<.>/?]+$/, it disallows the following characters:
    • whitespace characters (\r, \n, \t, and \f)
    • dashes (-)
    • carets (^)
    • backticks (`)
    • exclamation points (!)
    • at signs (@)
    • number signs (#)
    • dollar signs ($)
    • percent signs (%)
    • ampersands (&)
    • asterisks (*)
    • parentheses (())
    • underscores (_)
    • equal signs (=)
    • plus signs (+)
    • square brackets ([])
    • curly braces ({})
    • pipes (|)
    • semicolons (;)
    • colons (:)
    • single quotes (')
    • double quotes (")
    • commas (,)
    • angle brackets (<>)
    • periods (.)
    • forward slashes (/)
    • question marks (?)
  • noWhitespace - Disallows whitespace characters (\r, \n, \t, and \f). Defined as /^\S*$/.
  • numeric - Only allows numeric characters. Defined as /^(\d+)$/.
  • numericReal - Only allows real number values. Defined as /^(\d+\.?\d*|\.\d+|\-\d+\.?\d*|\-\.\d+)$/, it allows numbers in the following formats:
    • 1234
    • 12.34
    • .1234
    • -1234
    • -12.34
    • -.1234
  • phone - Only allows valid phone numbers. Defined as /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/, it allows phone numbers in the following formats:
    • (123)-456-7890
    • (123).456.7890
    • (123) 456 7890
    • 123-456-7890
    • 123.456.7890
    • 123 456 7890
  • phoneInternational - Similar to the phone validation, but allows for an optional one to four preceding numbers. Defined as /^(\d{1,4}[-. ]?)?\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/.
  • zipCode - Only allows five character numeric values. Defined as /^\d{5}$/.
  • zipCode+4 - Similar to the zipCode validation, but allows for an optional plus-four code. Defined as /^\d{5}(\-\d{4})?$/.
  • match - Asserts that a field value matches the value of another field. Its value must be set to another existing field.

Example:


{
  "rule": "match",
  "value": "confirmPasswordField",
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

  • matchOptions - Protects against invalid input on select fields by enforcing that the value submitted be one of the options defined in the field. Set this to false only if you plan on dynamically populating the select options yourself. This is added to select fields by default.

Example:


{
  "rule": "matchOptions",
  "value": True
}

  • maxLength - Asserts that the value of a field is at most the length set as the value of this validation.

Example:


{
  "rule": "maxLength",
  "value": 30,
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

  • minLength - Asserts that the value of a field is at least the length set as the value of this validation.

Example:


{
  "rule": "minLength",
  "value": 4,
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

  • minYears - Asserts that the value from a dateselect field is at least so many years in the past.

Example:


{
  "rule": "minYears",
  "value": 18,
  "message": {
    "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
  }
}

  • required - Asserts that a value is provided for this field. Set to true to enable this validation.

Example:


{
  "rule": "required",
  "value": true,
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

  • unique - Asserts that the value of this field is unique when compared to all records within the Janrain application. Set to true to enable this validation.

Example:


{
  "rule": "unique",
  "value": true,
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }

}

  • whitelist - Takes a list of allowed strings as its value. All other strings are disallowed.

Example:


{
  "rule": "whitelist",
  "value": ["only allow this","or_this_one!"],
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

  • clientFunctionName - Name of the function to use for validation on the client.

Example:


{
  "rule": "clientFunctionName",
  "value": "functionName",
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

  • serverRegexSetting - Server Setting of regex to use for validation.

Example:


{
  "rule": "serverRegexSetting",
  "value": "serverRegexSetting",
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

checkbox

dateselect

email

password

radio

select

text

textarea

blacklist

-

-

-

-

-

-

yes

-

format

-

-

yes*

yes

-

-

yes

yes

match

-

-

yes

yes

yes

yes

yes

-

matchOptions

-

-

-

-

-

yes

-

-

maxLength

-

-

yes

yes

-

-

yes

yes

minYears

-

yes

-

-

-

-

-

-

required

yes

yes

yes

yes

yes

yes

yes

yes

unique

-

-

yes

-

-

-

yes

-

whitelist

-

-

-

-

-

-

yes

-

clientFunctionName

-

yes

yes

yes

-

yes

yes

yes

serverRegexSetting

-

yes

yes

yes

-

yes

yes

yes

*: Fields of type email check for correctly-formatted emails by default. This cannot be overridden.

Full Examples

Full Example: checkbox


{
  "type": "checkbox",
  "name": "myCustomCheckboxField",
  "schemaAttribute": "optIn.status",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "preChecked": true,
  "submitValue": "yes",
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

Full Example: dateselect


{
  "name": "birthdate",
  "schemaAttribute": "birthday",
  "type": "dateselect",
  "label": {
    "key": "8122c314a4e9d558f6d3eedfb2446376"
  },
  "yearLabel": {
    "key": "acb8b9cedb63cb5930bae0fb1c2d50cc"
  },
  "monthLabel": {
    "key": "ace9326798de56c595568a7a4141972c"
  },
  "dayLabel": {
    "key": "6f44a1db770c928b0d40bb980548f43d"
  },
  "monthNames": [
    {
      "key": "66fcba24722d94d03167df4d29a3fcde"
    },{
      "key": "eec9c536de325f7f66669a7a61a55fc0"
    },{
      "key": "b8a35f47cfde6c15643c74804f9a6421"
    },{
      "key": "399c58387be99853b53ffc4f778814ab"
    },{
      "key": "ab66d779cf23720afbc4f2c49a296728"
    },{
      "key": "9089a6c3cc7b9d447c5aa870a38a49bf"
    },{
      "key": "24ea0188feb2be9c0a6fc0fffa329009"
    },{
      "key": "f814c7e7884980bfbe637bc8b7d5a798"
    },{
      "key": "cbbd277bc1b7f3034d4b8a5fc7c0a717"
    },{
      "key": "17ef13bbd9bd987fc16b4a26665e99ce"
    },{
      "key": "dd1b34fbac69ea3440260d0b25f660ea"
    },{
      "key": "368ace206c6cd848a8eb028fcf44a895"
    }
  ],
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    },{
      "rule": "minYears",
      "value": 18,
      "message": {
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
      }
    }
  ]
}

Full Example: email


{
  "type": "email",
  "name": "myCustomEmailField",
  "schemaAttribute": "email",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "socialProfileData": "profile.email",
  "placeholder": "6e15067b-2ca5-43c3-af96-930766d63375",
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

Full Example: password


{
  "type": "password",
  "name": "myCustomPasswordField",
  "schemaAttribute": "password",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "placeholder": "6e15067b-2ca5-43c3-af96-930766d63375",
  "validation": [
    {
      "rule": "minLength",
      "value": 16,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    },{
      "rule": "match",
      "value": "myCustomPasswordConfirmField",
      "message": {
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
      }
    }
  ]
}

Full Example: radio


{
  "type": "radio",
  "name": "myCustomRadioField",
  "schemaAttribute": "favorites.breakfastFood",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "options": [
    {
      "selected": true,
      "label": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      },
      "value": "waffles"
    },
    {
      "label": {
        "key": "c8050744-9b1d-4360-89e7-b37802d59c4a"
      },
      "value": "pancakes"
    }
  ],
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

Full Example: select


{
  "type": "select",
  "name": "myCustomSelectField",
  "schemaAttribute": "favorites.lunchFood",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "options": [
    {
      "selected": true,
      "label": {
        "8a8508aa-f939-472b-bad2-59f6c0089a60"
      },
      "value": "hotdogs"
    },
    {
      "label": {
        "c8050744-9b1d-4360-89e7-b37802d59c4a"
      },
      "value": "hamburgers"
    }
  ],
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

Full Example: text


{
  "type": "text",
  "name": "myCustomTextField",
  "schemaAttribute": "displayName",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "socialProfileData": "profile.displayName",
  "placeholder": "6e15067b-2ca5-43c3-af96-930766d63375",
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    },{
      "rule": "unique",
      "value": true,
      "message": {
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
      }
    }
  ]
}

Full Example: textarea


{
  "type": "textarea",
  "name": "myCustomTextareaField",
  "schemaAttribute": "profileBlurb",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "socialProfileData": "profile.aboutMe",
  "placeholder": "6e15067b-2ca5-43c3-af96-930766d63375",
  "validation": [
    {
      "rule": "maxLength",
      "value": 500,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}