Forms are defined by JSON objects, which you can add to the Custom settings sections throughout many integration resources, such as connections, exports, and imports. Built-in definitions make it easy for you to display common form fields, such as radio buttons and freeform text entry.
To see these fields in action, turn on Developer mode, go to Tools > Dev playground and select Form builder : Field dictionary to open the example JSON.
Contents
Required and optional form field settings
All form fields have specific options that you can use to control their appearance and behavior. For example, the first three required items below are the minimum needed to show the custom input field, and the last two values refine its appearance:
"fieldMap": {
"MiddleName": {
"id": "MiddleName",
"name": "MiddleName",
"type": "text",
"label": "Enter your middle name",
"helpText": "Tell us your middle name,<br /> initial, or type N/A."
}
}
Required settings |
Optional settings |
|
|
|
|
id
Required |
Yes |
Format |
String |
Values |
Must be the same as the form field’s key |
Example |
"id": "FieldName" |
name
Required |
Yes |
Format |
String |
Values |
It may be unique from the id, if this same field is defined in one place and used in different instances in other forms or sections; in most cases, specify the same value as the form field’s key |
Example |
"name": "FieldName" |
type
Required |
Yes |
Format |
String |
Values |
Any supported field; see Available fields, below |
Example |
"type": "radiogroup" |
label
Required |
No |
Format |
String |
Values |
The instructions that you want to precede the field (or follow it in the case of a checkbox) |
Example |
"label": "Are you sure you want to continue?" |
helpText
Required |
No |
Format |
String, HTML tags allowed |
Values |
Additional content to be shown when the help ( ) button is clicked |
Example |
"helpText": "If this doesn't make sense, ping Debbie in Slack." |
description
Required |
No |
Format |
String |
Values |
Explanatory text that is displayed below the form field |
Example |
"description": "Double-check your response, because it may change how the orders are updated in Salesforce." |
required
Applies to |
All fields except checkboxes |
Required |
No |
Format |
Boolean |
Values |
- true – label is in bold*, validated by the form
- false [default]
|
Example |
"required": true |
inputType
Applies to |
Text input ("type": "text" ) |
Required |
No |
Format |
String |
Values |
- number – only numeric input accepted
- password – masked characters
|
Example |
"inputType": "number" |
multiline
Applies to |
Text input ("type": "text" ) |
Required |
No |
Format |
Boolean |
Values |
- true – appears like an HTML <textarea> tag
- false – single line of text input [default]
|
Example |
"multiline": true |
rowsMax
Applies to |
Text input ("type": "text" ) |
Required |
No |
Format |
Numeric |
Example |
"rowsMax": 5 |
defaultValue
Required |
No |
Format |
String |
Values |
The selected option or suggested content that you want to provide for the user when the form is first loaded |
Example |
"defaultValue": "(415) " |
delimiter
Applies to |
Text input ("type": "text" ) |
Required |
No |
Format |
String |
Values |
Any character or set of characters is allowed – it will have no change to the form’s appearance, but the custom settings output will be split into an array delimited by the value supplied |
Example |
"delimiter": "," |
options (simple set)
Applies to |
Various fields, where "type" is one of the following:
|
Required |
No |
Format |
Array of strings |
Values |
The list of items that you want to offer:
- The simple set options differ from the value pairs in that the option name is also its value returned in the custom settings
- Items are sorted alphabetically
|
Example |
"options": [ { "items": [
"Create",
"Update",
"Delete" ] } ]
|
options (arrays of labels and values)
Applies to |
Various fields, where "type" is one of the following:
|
Required |
No |
Format |
Nested array of label-value pairs |
Values |
The list of items that you want to offer:
- The label is shown in the form, while only its value is returned in the custom settings
- Items are sorted alphabetically
|
Example |
"options": [
{
"label": "United States",
"value": "us"
},
{
"label": "United Kingdom",
"value": "uk"
},
{
"label": "Australia",
"value": "oz"
}
]
|
mode
Applies to |
Editor ("type": "editor" ) |
Required |
No |
Format |
String |
Values |
|
Example |
"mode": "json" |
keyName
Applies to |
Key-value pairs ("type": "keyvalue" ) |
Required |
No |
Format |
String |
Values |
The placeholder tip that you want displayed for the key name |
Example |
"keyName": "header-name" |
valueName
Applies to |
Key-value pairs ("type": "keyvalue" ) |
Required |
No |
Format |
String |
Values |
The placeholder tip that you want displayed for the value (input on the right) |
Example |
"valueName": "your-value" |
showDelete
Applies to |
Key-value pairs ("type": "keyvalue" ) |
Required |
No |
Format |
Boolean |
Values |
- true – trash can (delete) button appears to the right of the pair
- false – no option for the user to delete a line [default]
|
Example |
"showDelete": true |
visibleWhen
Required |
No |
Format |
Array |
Values |
- field – points to the key of another field
- is – a list of possible values for the other field, which – after user interaction – will make this field visible if true
|
Example |
"visibleWhen": [
{
"field": "formFieldDefined",
"is": [
"Proposal"
]
}
]
|
Available fields
Custom form fields are always children of the Form builder’s fieldMap object. Minimal JSON schemas are demonstrated below for the most commonly used form fields. However, this list is not exhaustive; leave a comment below if you see a specific form field in integrator.io for which you would like to see an example definition.
Form fields with sample definitions |
|
|
|
Advanced field editor
JSON definition |
"txtEditor": {
"id": "txtEditor",
"name": "txtEditor",
"type": "editor",
"label": "Additional JSON field",
"mode": "json"
}
|
Resulting field |
 |
Typical Custom settings response |
{
"txtEditor": "{\n \"sale\": \"declined\"\n}"
}
|
Checkbox
JSON definition |
"disclaim": {
"id": "disclaim",
"name": "disclaim",
"type": "checkbox",
"label": "Of course I have read the terms & conditions carefully"
}
|
Resulting field |
 |
Typical Custom settings response |
{
"disclaim": true
}
|
Date selector
JSON definition |
"createdAfter": {
"id": "createdAfter",
"name": "createdAfter",
"type": "date",
"label": "Created after"
}
|
Resulting field |
 |
Typical Custom settings response |
{
"createdAfter": "07/04/2020"
}
|
Drop-down list
JSON definition |
"province": {
"id": "province",
"name": "province",
"type": "select",
"label": "Province",
"options": [
{
"items": [
"Ontario",
"Quebec",
"Manitoba"
]
}
]
}
|
Resulting field |
 |
Typical Custom settings response |
{
"province": "Ontario"
}
|
Key-value pairs
JSON definition |
"keyPairs": {
"id": "keyPairs",
"name": "keyPairs",
"type": "keyvalue",
"label": "Contact numbers",
"keyName": "Type (home/office/mobile)",
"valueName": "Phone number",
"showDelete": true
}
|
Resulting field |
 |
Typical Custom settings response |
{
"keyPairs": [
{
"Type (home/office/mobile)": "home",
"Phone number": "202-456-1111"
},
{
"Type (home/office/mobile)": "office",
"Phone number": "0207 270 1234, ext. 3"
}
]
}
|
Multi-select list
JSON definition |
"roleInOrg": {
"id": "roleInOrg",
"name": "roleInOrg",
"type": "multiselect",
"label": "Select the functions that apply",
"options": [
{
"items": [
{
"label": "Accounting",
"value": "acctg"
},
{
"label": "Human Resources",
"value": "hr"
}
]
}
]
}
|
Resulting field |
 |
Typical Custom settings response |
{
"roleInOrg": [
"hr",
"acctg"
]
}
|
Radio buttons
JSON definition |
"pickOne": {
"id": "pickOne",
"name": "pickOne",
"type": "radiogroup",
"label": "Admin level",
"options": [
{
"items": [
{
"label": "Yes",
"value": "1"
},
{
"label": "No",
"value": "0"
}
]
}
]
}
|
Resulting field |
 |
Typical Custom settings response |
{
"pickOne": "1"
}
|
Text input – single or multiline
JSON definition |
"myTxtField": {
"id": "myTxtField",
"name": "myTxtField",
"type": "text",
"label": "Reason for editing my clean export"
}
|
Resulting field |
 |
Typical Custom settings response |
{
"myTxtField": "It stopped working"
}
|
Also see the multiline and rowsMax options.
Text input – delimited
JSON definition |
"listOcodes": {
"id": "listOcodes",
"name": "listOcodes",
"type": "text",
"delimiter": ",",
"label": "Error codes, separated by a comma"
}
|
Resulting field |
 |
Typical Custom settings response |
{
"listOcodes": [
"123",
"45a",
"67b"
]
}
|
Text input – number
JSON definition |
"storyPoints": {
"id": "storyPoints",
"name": "storyPoints",
"type": "text",
"inputType": "number",
"label": "Story points"
}
|
Resulting field |
 |
Typical Custom settings response |
{
"storyPoints": 13
}
|
Text input – password
JSON definition |
"token": {
"id": "token",
"name": "token",
"type": "text",
"inputType": "password",
"label": "API token",
"required": true
}
|
Resulting field |
 |
Typical Custom settings response |
{
"token": "987a654b321c"
}
|
Toggle switch
JSON definition |
"turnOn": {
"id": "turnOn",
"name": "turnOn",
"type": "toggle",
"label": "Primary connection",
"options": [
{
"label": "Yes",
"value": true
},
{
"label": "No",
"value": false
}
]
}
|
Resulting field |
 |
Typical Custom settings response |
{
"turnOn": true
}
|
Type: Refreshable drop-down list
The Refreshable dropdown list form field allows you to create a dropdown list of items, similar to the standard Select option. However, for Refreshable dropdown list, the dropdown list can be updated using a virtual export from your application. Sometimes, you’ll need to use a transformation in your virtual export. Below is an example configuration using a NetSuite connection and Salesforce SOQL with transformation rules.
Example 1: JSON definition using NetSuite connection |
"refreshableSelect":{
"id":"refreshableSelect",
"name":"refreshableSelect",
"type":"exportSelect",
"helpText":"myHelpText",
"label":"some url with handlebar support.",
"resource":{
"virtual":{
"_connectionId":"myNetSuiteConnectionID",
"_MyconnectorId":"myIAID (only needed for IAs)",
"asynchronous":true,
"netsuite":{
"type":"restlet",
"skipGrouping":true,
"restlet":{
"recordType":"account",
"columns":[
{
"name":"internalId",
"label":"value"
},
{
"name":"name",
"label":"label",
"sort":"true"
}
]
}
}
}
}
}
|
Example 2: Using Salesforce SOQL and transform rules |
{
"id": "refreshableSelect",
"name": "refreshableSelect",
"type": "exportSelect",
"helpText": "Fetch the list of valid Accounts from Salesforce. This
is the default Account for Salesforce ",
"label": "Select default account from Salesforce",
"resource": {
"virtual": {
"name": "Get Salesforce accounts",
"_connectionId": "5daef2e628d53f7fb9036688",
"asynchronous": true,
"sandbox": false,
"test": {
"limit": 10
},
"salesforce": {
"type": "soql",
"api": "rest",
"soql": {
"query": "SELECT ID,Name FROM Account"
},
"distributed": {
"referencedFields": [],
"disabled": false,
"userDefinedReferencedFields": [],
"relatedLists": []
}
},
"transform": {
"type": "expression",
"expression": {
"version": "1",
"rules": [
[
{
"extract": "Name",
"generate": "label"
},
{
"extract": "Id",
"generate": "value"
}
]
]
},
"version": "1",
"rules": [
[
{
"extract": "Name",
"generate": "label"
},
{
"extract": "Id",
"generate": "value"
}
]
]
},
"adaptorType": "SalesforceExport"
}
}
}
|
Resulting field |
 
|
URL input
JSON definition |
"productsUrl": {
"id": "productsUrl",
"name": "productsUrl",
"type": "relativeuri",
"label": "URL for exporting products"
}
|
Resulting field |
 |
Typical Custom settings response |
{
"productsUrl": "prod/v1/"
}
|
Form layout options
Each custom form can have an optional layout object (at the same level as fieldMap), which determines the following positioning in the form:
Specify the order of custom form fields
The order of the fields’ keys in the layout object has precedence over the order in which you placed them in the fieldMap object.
Consider the following form definition, in which firstName and lastName are displayed according the to the layout order:
{
"fieldMap": {
"lastName": {
"id": "lastName",
"name": "lastName",
"type": "text",
"label": "What is your family name?"
},
"firstName": {
"id": "firstName",
"name": "firstName",
"type": "text",
"label": "What is your given name?"
}
},
"layout": {
"fields": [
"firstName",
"lastName"
]
}
}
Establish a multi-column layout
The layout object supports a type option that lets you position each field into two or more columns. Then, you can label and order the fields in each column as an item in the containers object.
The following definition creates four fields, within two columns:
{
"fieldMap": {
"firstName": {
"id": "firstName",
"name": "firstName",
"type": "text",
"label": "What is your given name?"
},
"lastName": {
"id": "lastName",
"name": "lastName",
"type": "text",
"label": "What is your family name?"
},
"office": {
"id": "office",
"name": "office",
"type": "select",
"label": "Office",
"options": [
{
"items": [
"Stirling",
"Capetown"
]
}
]
},
"offsite": {
"id": "offsite",
"name": "offsite",
"type": "checkbox",
"label": "Remote worker"
}
},
"layout": {
"type": "column",
"containers": [
{
"label": "Name",
"fields": [
"firstName",
"lastName"
]
},
{
"label": "Location",
"fields": [
"office",
"offsite"
]
}
]
}
}
Organize form fields into collapsible sections
The layout object also exposes a "type": "collapse"
option that creates one or more collapsible sections, such as the Advanced and Custom settings groupings that you see in built-in integrator.io forms. Then, you can label and order the fields in each section as an item in the containers object.
The example below defines two form fields within a new section:
{
"fieldMap": {
"versionString": {
"id": "versionString",
"name": "versionString",
"type": "text",
"label": "API version",
"required": true
},
"serverType": {
"id": "serverType",
"name": "serverType",
"type": "toggle",
"label": "Account type",
"defaultValue": "prod",
"options": [
{
"label": "Production",
"value": "prod"
},
{
"label": "Sandbox",
"value": "sb"
}
]
}
},
"layout": {
"type": "collapse",
"containers": [
{
"label": "Environment",
"fields": [
"versionString",
"serverType"
]
}
]
}
}
Section is open by default, since the field API version is required.
Organize form fields into boxed sections
The layout object also exposes a "type": "box"
option that contains the named form fields. Then, you can order the fields in each section as an item in the containers object.
The example below defines two form fields within a new section:
{
"fieldMap": {
"versionString": {
"id": "versionString",
"name": "versionString",
"type": "text",
"label": "API version"
},
"serverType": {
"id": "serverType",
"name": "serverType",
"type": "toggle",
"label": "Account type",
"defaultValue": "prod",
"options": [
{
"label": "Production",
"value": "prod"
},
{
"label": "Sandbox",
"value": "sb"
}
]
}
},
"layout": {
"type": "box",
"containers": [
{
"fields": [
"versionString",
"serverType"
]
}
]
}
}
Organize form fields into indented sections
The layout object also exposes a "type": "indent"
option that groups the referenced fields into an indented section. Then, you can label and order the fields in each section as an item in the containers object.
The example below defines two form fields within a new section:
{
"fieldMap": {
"versionString": {
"id": "versionString",
"name": "versionString",
"type": "text",
"label": "API version"
},
"serverType": {
"id": "serverType",
"name": "serverType",
"type": "toggle",
"label": "Account type",
"defaultValue": "prod",
"options": [
{
"label": "Production",
"value": "prod"
},
{
"label": "Sandbox",
"value": "sb"
}
]
}
},
"layout": {
"type": "indent",
"containers": [
{
"label": "Environment",
"fields": [
"versionString",
"serverType"
]
}
]
}
}
Comments
3 comments
There is an extra inputType "staticMap" that allows you to do make a mapping table based on data that is sourced live from the source&target systems.
There is an excellent example by Tyler in the following link:
https://docs.celigo.com/hc/en-us/community/posts/11906392792347-Querying-NetSuite-Records-in-Custom-Form-Builder-Settings
There is an extra type "exportSelect" that allows you to do a virtual export, and choose one of the results for your custom setting:
Make sure that your virtual export returns 'label' and 'value' as the value that will be shown and the value that is saved in the custom setting.
Bas van Ditzhuijzen one additional one is having a refreshable multi select. If you take the exportSelect option, and just add another field for "multiselect": true, then you can have a live refreshable multiselect field. Kathyana Rule and I are actually working on updating this doc as we speak. Stay tuned!
Please sign in to leave a comment.