Articles in this section

Common form fields

Stephen Brandt
Updated

Forms are defined by JSON objects, which you can add to the 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.

Tip

To see these fields in action, go to Build+Playground and select Form builder : Field dictionary to open the example JSON.

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."
  }
}
360091980992-custom-forms-12.png

Required

Optional

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 also Available fields

Example

"type": "radiogroup"

allowFreeText

Required

No

Format

Boolean

Values

When set to false, users can only select from the predefined list (custom input is not allowed). When set to true, users can enter and save custom input. As they type, the list automatically filters down based on their input (search is supported by default). The search bar itself is not displayed, and there is no need to explicitly enable the showSearch field.

Example

Applies to various fields of the following types:

  • staticMap

  • select

  • exportSelect where multiselect = false

copyToClipboard

Required

No

Format

Boolean

Values

  • Adds a Copy button (copy.svg​​) next to the field so the value can easily be copied. It is sometimes used in conjunction with defaultDisabled.

Example

 
{
  "fieldMap": {
    "invokeUrl": {
      "id": "invokeUrl",
      "name": "invokeUrl",
      "type": "text",
      "label": "Export invoke URL",
      "helpText": "Use this URL to invoke your export via HTTP request.",
      "defaultValue": "https://api.integrator.io/v1/exports/687••••f48/invoke",
      "copyToClipboard": true
    }
  }
}
disabled_and_copy.png

defaultDisabled

Required

No

Format

Boolean

Values

  • Enables read-only mode so the user can't edit the field. It is sometimes used in conjunction with copyToClipboard.

Example

 
{
  "fieldMap": {
    "invokeUrl": {
      "id": "invokeUrl",
      "name": "invokeUrl",
      "type": "text",
      "label": "Export invoke URL",
      "helpText": "Use this URL to invoke your export via HTTP request.",
      "defaultValue": "https://api.integrator.io/v1/exports/687••••f48/invoke",
      "defaultDisabled": true
    }
  }
}
disabled_and_copy.png

defaultRequired

Required

No

Format

Boolean

Values

  • true

  • false

Example

"defaultRequired": true

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)"

defaultVisible

Required

No

Format

Boolean

Values

  • true

  • false

Example

"defaultVisible": true

deleteWhen

This property deletes a field's value from the form data when any of the specified conditions are satisfied, so you can decide when to include or remove certain fields.

  • Operates on an OR logic; if any rule within the array evaluates to true, the field value is expunged from the form data.

  • The field value is entirely purged from the submitted data.

  • The field may retain visibility within the user interface; however, its value will be excluded from the final form submission.

Required

No

Format

Array

Values

The setting accepts multiple objects, each with a field key and is or isNot value arrays. A field is deleted if any object is true, meaning a value matches any value in the is array and doesn't match any value in the isNot array.

  • field – points to the key of another field

  • is – a list of possible values for the other field, which – after user interaction – will delete the field if true

  • isNot – a list of possible values for the other field, which – after user interaction – will delete the field if not true

Examples

{
  "fieldMap": {
    "select": {
      "id": "select",
      "name": "select",
      "type": "select",
      "multiline": true,
      "helpText": "Optional help for setting: A",
      "label": "Select frequency",
      "options": [
        {
          "items": [
            "Never",
            "1 hour",
            "2 hours"
          ]
        }
      ]
    },
    "selectRemove": {
      "id": "selectRemove",
      "name": "selectRemove",
      "type": "select",
      "multiline": true,
      "label": "Select (RemoveWhen)",
      "options": [
        {
          "items": [
            "15 mins",
            "30 mins",
            "45 mins"
          ]
        }
      ],
      "removeWhen": [
        {
          "field": "select",
          "is": [
            "Never"
          ]
        }
      ]
    },
    "selectDelete": {
      "id": "selectDelete",
      "name": "selectDelete",
      "type": "select",
      "multiline": true,
      "label": "Select (DeleteWhen)",
      "options": [
        {
          "items": [
            "15 mins",
            "30 mins",
            "45 mins"
          ]
        }
      ],
      "deleteWhen": [
        {
          "field": "select",
          "is": [
            "Never"
          ]
        }
      ]
    }
  },
  "layout": {
    "fields": [
      "select",
      "selectRemove",
      "selectDelete"
    ]
  }
}

deleteWhenAll

This property deletes a field's value from the form data when all of the specified conditions are satisfied, so you can decide when to include or remove certain fields.

  • Employs an AND logic; all rules within the array must evaluate to true for the field value to be deleted.

  • The field value is entirely purged from the submitted data.

  • The field may retain visibility within the user interface; however, its value will be excluded from the final form submission.

Required

No

Format

Array

Values

The setting accepts multiple objects, each with a field key and is or isNot value arrays. A field is deleted if all objects are true, meaning a value matches all values in the is array and doesn't match all the values in the isNot array.

  • field – points to the key of another field

  • is – a list of possible values for the other field, which – after user interaction – will delete the field if true

  • isNot – a list of possible values for the other field, which – after user interaction – will delete the field if not true

Examples

{
  "fieldMap": {
    "select": {
      "id": "select",
      "name": "select",
      "type": "select",
      "multiline": true,
      "helpText": "Optional help for setting: A",
      "label": "Select frequency",
      "options": [
        {
          "items": [
            "Never",
            "1 hour",
            "2 hours"
          ]
        }
      ]
    },
    "selectRemove": {
      "id": "selectRemove",
      "name": "selectRemove",
      "type": "select",
      "multiline": true,
      "label": "Select (RemoveWhen)",
      "options": [
        {
          "items": [
            "15 mins",
            "30 mins",
            "45 mins"
          ]
        }
      ],
      "removeWhen": [
        {
          "field": "select",
          "is": [
            "Never"
          ]
        }
      ]
    },
    "selectDelete": {
      "id": "selectDelete",
      "name": "selectDelete",
      "type": "select",
      "multiline": true,
      "label": "Select (DeleteWhen)",
      "options": [
        {
          "items": [
            "15 mins",
            "30 mins",
            "45 mins"
          ]
        }
      ],
      "deleteWhen": [
        {
          "field": "select",
          "is": [
            "Never"
          ]
        }
      ]
    }
  },
  "layout": {
    "fields": [
      "select",
      "selectRemove",
      "selectDelete"
    ]
  }
}

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": ","

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

disabledWhen

Required

No

Format

Array

Values

The disabledWhen setting controls whether the field is disabled under certain conditions. The setting accepts multiple objects, each with a field key and is or isNot value arrays. A field becomes disabled if any object is true, meaning a value matches any value in the is array and doesn't match any value in the isNot array.

  • field – points to the key of another field

  • is – a list of possible values for the other field, which – after user interaction – will disable the field if true

  • isNot – a list of possible values for the other field, which – after user interaction – will disable the field if not true

Examples

"disabledWhen": [
  {
    "field": "formFieldDefined",
    "is": [
      "Proposal", "Test", "Example"
      ]
},
{
    "field": "radiobutton",
    "is": [ 
      "Proposal", "Test", "Example"
    ]
  },
{
    "field": "formFieldDefined",
    "isNot": [
      "Proposal", "Test", "Example"
    ]
  }
]

"disabledWhen": {
"id": "disabledWhen",
"name": "disabledWhen",
"type": "select",
"label": "disabled when",
"defaultValue": "Hyderabad",
"description": "This field will be visible only when radiogroup is set as create and select is set as USA or when radiogroup is set as update and select is set as Canada",
 "options": [
  {
   "items": [
     "Delhi",
     "Hyderabad",
     "Chennai"
    ]
   }
  ],
  "disabledWhen": [
   { "OR":[
     {"AND":
      [{
       "field": "radiogroup",
       "is": [
        "Create"
        ]
       },
      {
      "field": "select",
       "is": [
        "USA"
        ]
       }
      ]
     },
     {"AND":
      [{
       "field": "radiogroup",
        "is": [
         "Update"
        ]
       },{
      "field": "select",
       "is": [
        "Canada"
        ]
       }
      ]
     }
    ]
   }
  ]
 }

disabledWhenAll

Required

No

Format

Array

Values

The disabledWhenAll setting controls whether the field is disabled under certain conditions. The setting accepts multiple objects, each with a field key and is or isNot value arrays. A field becomes disabled if all objects are true, meaning the values match all values in the is array, and don't match any value in the isNot array.

  • field – points to the key of another field

  • is – a list of possible values for the other field, which – after user interaction – will disable the field if true

  • isNot – a list of possible values for the other field, which – after user interaction – will disable the field if not true

Examples

"disabledWhenAll": [
  {
    "field": "formFieldDefined",
    "is": [
      "Proposal", "Test", "Example"
      ]
},
{
    "field": "radiobutton",
    "is": [ 
      "Proposal", "Test", "Example"
    ]
  },
{
    "field": "formFieldDefined",
    "isNot": [
      "Proposal", "Test", "Example"
    ]
  }
]

"disabledWhenAll": {
"id": "disabledWhenAll",
"name": "disabledWhenAll",
"type": "select",
"label": "disabled when all",
"defaultValue": "Hyderabad",
"description": "This field will be visible only when radiogroup is set as create and select is set as USA or when radiogroup is set as update and select is set as Canada",
 "options": [
  {
   "items": [
     "Delhi",
     "Hyderabad",
     "Chennai"
    ]
   }
  ],
  "disabledWhenAll": [
   { "OR":[
     {"AND":
      [{
       "field": "radiogroup",
       "is": [
        "Create"
        ]
       },
      {
      "field": "select",
       "is": [
        "USA"
        ]
       }
      ]
     },
     {"AND":
      [{
       "field": "radiogroup",
        "is": [
         "Update"
        ]
       },{
      "field": "select",
       "is": [
        "Canada"
        ]
       }
      ]
     }
    ]
   }
  ]
 }

displayAfter

Required

No

Format

String

Values

The displayAfter form field setting allows you to display form fields at a desired location in your export or import forms. For example, if you want to display a custom field ( roleInOrg) after the API endpoint field you can use the JSON path export.http._httpConnectorEndpointId) available in the help text to point to the new field’s location. In the example below, the new roleInOrg field will be displayed after the API endpoint field.

Note: The displayAfter feature is only available for connections with simple and HTTP view options.

Example

 
 
"roleInOrg": {
  "id": "roleInOrg",
  "name": "roleInOrg",
  "type": "multiselect",
  "label": "Select the functions that apply",
  "displayAfter" : "export.http._httpConnectorEndpointId",
  "options": [
    {
      "items": [
        { "label": "Accounting",
          "value": "acctg"
        },
        {
          "label": "Human Resources",
          "value": "hr"
        }
      ]
    }
  ]
}}
15708328388123-Screenshot_2023-05-18_at_8.24.06_AM.png

endAdornment & startAdornment

Required

No

Format

String

Values

The values of the endAdornment and startAdornment fields aren't saved. They only provide context to what the user should enter into the text field. This can only be used with text field type.

Example

 
{
  "fieldMap": {
    "instance": {
      "type": "text",
      "id": "instanceName",
      "name": "instanceName",
      "startAdornment": "https://",
      "endAdornment": ".service-now.com",
      "label": "ServiceNow instance",
      "required": true
    }
  }
}
adornment.png

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

inputType

Applies to

Text input ("type": "text")

Required

No

Format

String

Values

  • number – only numeric input accepted

  • password – masked characters

Example

"inputType": "number"

keyName

Applies to

Key-value pairs ("type": "keyvalue")

Required

Yes

Format

String

Values

The placeholder tip that you want displayed for the key name

Example

"keyName": "header-name"

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?"

mode

Applies to

Editor ("type": "editor")

Required

No

Format

String

Values

  • csv

  • text

  • xml

  • json

Example

"mode": "json"

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

nativeFieldPath

Use the nativeFieldPath to enter the path to the native field you would like to display. When the form is saved with this field type, the value will be stored in the native field and custom settings.

Applies to

"type":"nativeField"

Required

No

Format

String

Values

"nativeFieldPath": "export.http.response.twoDArray.hasHeader"

Example

 
{
  "useAsPrimaryInterface": false,
  "fieldMap": {
    "hasHeaderNativeField": {
      "id": "hasHeaderNativeField",
      "name": "hasHeaderNativeField",
      "type": "nativeField",
      "nativeFieldPath": "export.http.response.twoDArray.hasHeader",
      "helpText": "Permissions assigned to you by IT.",
      "label": "test"
    }
  },
  "layout": {
    "fields": [
      "hasHeaderNativeField",
      "name"
    ]
  }
}

omitWhenHidden

Required

No

Format

Boolean

Values

  • true

  • false

Example

"omitWhenHidden": true

omitWhenValueIs

Required

No

Format

Array

Values

Omits the field when any of the array values are present.

Example

 
"omitWhenValueIs": [
        "Hyderabad"
      ]

options (simple set)

Applies to

Various fields, where "type" is one of the following:

  • "radiogroup"

  • "select"

  • "multiselect"

  • "toggle"

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:

  • "radiogroup"

  • "select"

  • "multiselect"

  • "toggle"

Required

No

Format

Nested array

Values

The label is displayed in the form, but only its value is returned in the custom settings. If you add "description": "IT Hub", along with the label and value fields in the object within the items array, it will appear in the drop-down along with the label.

Example

 
{
  "options": [
    {
      "items": [
        {
          "label": "Delhi",
          "value": "Delhi",
          "isActive": true,
          "isEnabled": false
        },
        {
          "label": "Hyderabad",
          "value": "Hyderabad",
          "isActive": false,
          "isEnabled": false
        },
        {
          "label": "Chennai",
          "value": "Chennai",
          "isActive": true,
          "isEnabled": false
        }
      ]
    }
  ]
}

order

If you don't specify, this field defaults to ascending. If both orderBy and order are missing, the original order is preserved where sort is not supported. In cases where sort is supported by default (ex. type = select), even if orderBy and order are missing, the list is sorted alphabetically by label and asc.

Applies to

Drop-down menus

Required

No

Format

String

Values

asc or desc

Example

"order": "asc"

 
{
  "fieldMap": {
    "selectField": {
      "id": "selectField",
      "name": "selectField",
      "type": "select",
      "label": "Selelct field",
      "order": "asc",
      "orderBy": "add1",
      "options": [
        {
          "items": [
            {
              "label": "Delhi",
              "value": "abc",
              "add1": "1"
            },
            {
              "label": "Hyderabad",
              "value": "xyz",
              "add1": "2"
            },
            {
              "label": "Chennai",
              "value": "mno",
              "add1": "3"
            }
          ]
        }
      ]
    }
  },
  "layout": {
    "fields": [
      "selectField"
    ]
  }
}

orderBy

Works in conjunction with the order field. If you don't specify the order field, it defaults to ascending (asc). If the drop-down list is an array of strings then use "orderBy": "value" to order the drop-down list.

If both orderBy and order are missing, the original order is preserved where sort is not supported. In cases where sort is supported by default (ex. type = select), even if orderBy and order are missing, the list is sorted alphabetically by label and asc.

Applies to

Drop-down menus

Required

No

Format

String

Values

label, value, or additionalField.

Example

"orderBy": "label"

 
{
  "fieldMap": {
    "selectField": {
      "id": "selectField",
      "name": "selectField",
      "type": "select",
      "label": "Selelct field",
      "order": "asc",
      "orderBy": "add1",
      "options": [
        {
          "items": [
            {
              "label": "Delhi",
              "value": "abc",
              "add1": "1"
            },
            {
              "label": "Hyderabad",
              "value": "xyz",
              "add1": "2"
            },
            {
              "label": "Chennai",
              "value": "mno",
              "add1": "3"
            }
          ]
        }
      ]
    }
  },
  "layout": {
    "fields": [
      "selectField"
    ]
  }
}

placeHolder

Required

No

Format

String

Values

Adds placeholder text to a dropdown when no option is selected.

Example

 
{
  "fieldMap": {
    "province": {
      "id": "province",
      "name": "province",
      "type": "select",
      "label": "Province",
      "placeholder": "ADD PLACEHOLDER TEXT HERE",
      "options": [
        {
          "items": [
            "Ontario",
            "Quebec",
            "Manitoba"
          ]
        }
      ]
    }
  }
}
Placeholder.png

removeWhen

This property sets a field's value to undefined when any of the specified conditions are met.

  • Utilizes an OR logic; if any rule in the array evaluates to true, the field value transitions to undefined.

  • The field value is set to undefined, but the field key persists within the form data.

  • This approach is less aggressive than deleteWhen, as it preserves the field structure.

removeWhen and removeWhenAll should only be used when building connectors.

Required

No

Format

Array

Values

The setting accepts multiple objects, each with a field key and is or isNot value arrays. A field is removed if any object is true, meaning a value matches any value in the is array and doesn't match any value in the isNot array.

  • field – points to the key of another field

  • is – a list of possible values for the other field, which – after user interaction – will remove the field if true

  • isNot – a list of possible values for the other field, which – after user interaction – will remove the field if not true

Example

{
  "fieldMap": {
    "select": {
      "id": "select",
      "name": "select",
      "type": "select",
      "multiline": true,
      "helpText": "Optional help for setting: A",
      "label": "Select frequency",
      "options": [
        {
          "items": [
            "Never",
            "1 hour",
            "2 hours"
          ]
        }
      ]
    },
    "selectRemove": {
      "id": "selectRemove",
      "name": "selectRemove",
      "type": "select",
      "multiline": true,
      "label": "Select (RemoveWhen)",
      "options": [
        {
          "items": [
            "15 mins",
            "30 mins",
            "45 mins"
          ]
        }
      ],
      "removeWhen": [
        {
          "field": "select",
          "is": [
            "Never"
          ]
        }
      ]
    },
    "selectDelete": {
      "id": "selectDelete",
      "name": "selectDelete",
      "type": "select",
      "multiline": true,
      "label": "Select (DeleteWhen)",
      "options": [
        {
          "items": [
            "15 mins",
            "30 mins",
            "45 mins"
          ]
        }
      ],
      "deleteWhen": [
        {
          "field": "select",
          "is": [
            "Never"
          ]
        }
      ]
    }
  },
  "layout": {
    "fields": [
      "select",
      "selectRemove",
      "selectDelete"
    ]
  }
}

removeWhenAll

This property sets a field's value to undefined when all of the specified conditions are met.

  • Utilizes an AND logic; all rules in the array must evaluate to true for the field value to become undefined.

  • The field value is set to undefined, but the field key persists within the form data.

  • This approach is less aggressive than deleteWhenAll, as it preserves the field structure.

removeWhen and removeWhenAll should only be used when building connectors.

Required

No

Format

Array

Values

The setting accepts multiple objects, each with a field key and is or isNot value arrays. A field is removed if all objects are true, meaning a value matches all values in the is array and doesn't match all values in the isNot array.

  • field – points to the key of another field

  • is – a list of possible values for the other field, which – after user interaction – will remove the field if true

  • isNot – a list of possible values for the other field, which – after user interaction – will remove the field if not true

Example

{
  "fieldMap": {
    "select": {
      "id": "select",
      "name": "select",
      "type": "select",
      "multiline": true,
      "helpText": "Optional help for setting: A",
      "label": "Select frequency",
      "options": [
        {
          "items": [
            "Never",
            "1 hour",
            "2 hours"
          ]
        }
      ]
    },
    "selectRemove": {
      "id": "selectRemove",
      "name": "selectRemove",
      "type": "select",
      "multiline": true,
      "label": "Select (RemoveWhen)",
      "options": [
        {
          "items": [
            "15 mins",
            "30 mins",
            "45 mins"
          ]
        }
      ],
      "removeWhen": [
        {
          "field": "select",
          "is": [
            "Never"
          ]
        }
      ]
    },
    "selectDelete": {
      "id": "selectDelete",
      "name": "selectDelete",
      "type": "select",
      "multiline": true,
      "label": "Select (DeleteWhen)",
      "options": [
        {
          "items": [
            "15 mins",
            "30 mins",
            "45 mins"
          ]
        }
      ],
      "deleteWhen": [
        {
          "field": "select",
          "is": [
            "Never"
          ]
        }
      ]
    }
  },
  "layout": {
    "fields": [
      "select",
      "selectRemove",
      "selectDelete"
    ]
  }
}

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

requiredWhen

Required

No

Format

Array

Values

The requiredWhen setting controls whether the field is required under certain conditions. The setting accepts multiple objects, each with a field key and is or isNot value arrays. A field becomes required if any object is true, meaning a value matches any value in the is array and doesn't match any value in the isNot array.

  • 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 required if true

  • isNot – a list of possible values for the other field, which – after user interaction – will make this field required if not true

Examples

"requiredWhen": [
  {
    "field": "formFieldDefined",
    "is": [
      "Proposal", "Test", "Example"
      ]
},
{
    "field": "radiobutton",
    "is": [ 
      "Proposal", "Test", "Example"
    ]
  },
{
    "field": "formFieldDefined",
    "isNot": [
      "Proposal", "Test", "Example"
    ]
  }
]

"requiredWhen": {
"id": "requiredWhen",
"name": "requiredWhen",
"type": "select",
"label": "required when",
"defaultValue": "Hyderabad",
"description": "This field will be visible only when radiogroup is set as create and select is set as USA or when radiogroup is set as update and select is set as Canada",
 "options": [
  {
   "items": [
     "Delhi",
     "Hyderabad",
     "Chennai"
    ]
   }
  ],
  "requiredWhen": [
   { "OR":[
     {"AND":
      [{
       "field": "radiogroup",
       "is": [
        "Create"
        ]
       },
      {
      "field": "select",
       "is": [
        "USA"
        ]
       }
      ]
     },
     {"AND":
      [{
       "field": "radiogroup",
        "is": [
         "Update"
        ]
       },{
      "field": "select",
       "is": [
        "Canada"
        ]
       }
      ]
     }
    ]
   }
  ]
 }

requiredWhenAll

Required

No

Format

Array

Values

The requiredWhenAll setting controls whether the field is required under certain conditions. The setting accepts multiple objects, each with a field key and is or isNot value arrays. A field becomes required if all objects are true, meaning the values match all values in the is array, and don't match any value in the isNot array.

  • 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 required if true

  • isNot – a list of possible values for the other field, which – after user interaction – will make this field required if not true

Examples

"requiredWhenAll": [
  {
    "field": "formFieldDefined",
    "is": [
      "Proposal", "Test", "Example"
      ]
},
{
    "field": "radiobutton",
    "is": [ 
      "Proposal", "Test", "Example"
    ]
  },
{
    "field": "formFieldDefined",
    "isNot": [
      "Proposal", "Test", "Example"
    ]
  }
]

"requiredWhenAll": {
"id": "requiredWhenAll",
"name": "requiredWhenAll",
"type": "select",
"label": "required when all",
"defaultValue": "Hyderabad",
"description": "This field will be visible only when radiogroup is set as create and select is set as USA or when radiogroup is set as update and select is set as Canada",
 "options": [
  {
   "items": [
     "Delhi",
     "Hyderabad",
     "Chennai"
    ]
   }
  ],
  "requiredWhenAll": [
   { "OR":[
     {"AND":
      [{
       "field": "radiogroup",
       "is": [
        "Create"
        ]
       },
      {
      "field": "select",
       "is": [
        "USA"
        ]
       }
      ]
     },
     {"AND":
      [{
       "field": "radiogroup",
        "is": [
         "Update"
        ]
       },{
      "field": "select",
       "is": [
        "Canada"
        ]
       }
      ]
     }
    ]
   }
  ]
 }

rowsMax

Applies to

Text input ("type": "text")

Required

No

Format

Numeric

Example

"rowsMax": 5

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

showSearch

Required

No

Format

Boolean

Values

When set to false, the search box is not visible in the dropdown list. When set to true, the search box is visible and allows the user to search the list items.

Example

Applies to various fields of the following types:

  • staticMap

  • select

  • multiselect

  • exportSelect

showSelectAll

Required

No

Format

Boolean

Values

When set to false, the select all option is NOT visible in the dropdown list. When set to true, the select all option is visible in the dropdown list, which allows users to select all the items in the list.

Example

Applies to various fields for the following types:

  • multiselect

  • exportSelect where multiselect = true

skipSort

Required

No

Format

Boolean

Values

  • When set to false, then the list is sorted alphabetically by label.

  • When set to true, the list is not sorted.

Example

 
{
  "fieldMap": {
    "compression": {
      "type": "select",
      "label": "Compression type",
      "skipSort": false,
      "options": [
        {
          "items": [
            {
              "label": "zlib",
              "value": "zlib"
            },
            {
              "label": "zip",
              "value": "zip"
            },
            {
              "label": "gzip",
              "value": "gzip"
            }
          ]
        }
      ]
    }
  }
}
skip_sort_false.png

skipSort set to false

skip_sort_true.png

skipSort set to true

storeAdditionalProperties

You can use storeAdditionalProperties field to store additional properties. All list type fields include an options argument, which requires a label and value, but only value is stored upon save.

Applies to

You can use storeAdditionalProperties with these list type fields:

  • select

  • multiselect

  • exportSelect

  • staticMap

  • toggle

  • radiogroup

Required

No

Format

Array or "all"

Values

When you set "storeAdditionalProperties": "all" , all fields within the options array are stored. To store a subset of fields, add an array with comma separated fields.

"storeAdditionalProperties": ["isActive","isEnabled"]

If storeAdditionalProperites isn't provided, the value field(s) will still be saved. If you're using the defaultValue field in conjunction with storeAdditionalProperties , then you must include every field you want to store.

"defaultValue": {"value": "Chennai","isActive": true,"isEnabled": false}

Example

{
  "fieldMap": {
    "mode": {
      "id": "mode",
      "name": "mode",
      "type": "radiogroup",
      "label": "Mode of operation",
      "storeAdditionalProperties": "all",
      "options": [
        {
          "items": [
            {
              "label": "Create",
              "value": "create",
              "isActive": true,
              "isEnabled": false
            },
            {
              "label": "Update",
              "value": "update",
              "isActive": false,
              "isEnabled": false
            },
            {
              "label": "Delete",
              "value": "delete",
              "isActive": true,
              "isEnabled": false
            }
          ]
        }
      ]
    },
    "selectField1": {
      "id": "selectField1",
      "name": "selectField1",
      "type": "select",
      "label": "Select",
      "defaultValue": {
        "value": "Chennai",
        "isActive": true
      },
      "storeAdditionalProperties": [
        "isActive"
      ],
      "options": [
        {
          "items": [
            {
              "label": "Delhi",
              "value": "Delhi",
              "isActive": true,
              "isEnabled": false
            },
            {
              "label": "Hyderabad",
              "value": "Hyderabad",
              "isActive": false,
              "isEnabled": false
            },
            {
              "label": "Chennai",
              "value": "Chennai",
              "isActive": true,
              "isEnabled": false
            }
          ]
        }
      ]
    },
    "multiselect": {
      "id": "multiselect",
      "name": "multiselect",
      "type": "multiselect",
      "label": "Select multiple items",
      "storeAdditionalProperties": [
        "isActive"
      ],
      "options": [
        {
          "items": [
            {
              "label": "USA",
              "value": "US",
              "isActive": true,
              "isEnabled": false
            },
            {
              "label": "Canada",
              "value": "CDN",
              "isActive": true,
              "isEnabled": false
            },
            {
              "label": "India",
              "value": "IN",
              "isActive": true,
              "isEnabled": false
            },
            {
              "label": "China",
              "value": "CH",
              "isActive": true,
              "isEnabled": false
            },
            {
              "label": "South Africa",
              "value": "SA",
              "isActive": true,
              "isEnabled": false
            },
            {
              "label": "Spain",
              "value": "SP",
              "isActive": true,
              "isEnabled": false
            },
            {
              "label": "Mexico",
              "value": "MX",
              "isActive": true,
              "isEnabled": false
            }
          ]
        }
      ]
    },
    "toggle": {
      "id": "toggle",
      "name": "toggle",
      "type": "toggle",
      "label": "Toggle button",
      "storeAdditionalProperties": [
        "isEnabled"
      ],
      "options": [
        {
          "label": "US",
          "value": "us",
          "isActive": true,
          "isEnabled": false
        },
        {
          "label": "Canada",
          "value": "cdn",
          "isActive": true,
          "isEnabled": false
        },
        {
          "label": "India",
          "value": "in",
          "isActive": true,
          "isEnabled": false
        }
      ]
    }
  },
  "layout": {
    "fields": [
      "mode",
      "selectField1",
      "multiselect",
      "toggle"
    ]
  }
}

supportHandlebars

You can use handlebars throughout your custom form configurations, which allow you to reference saved and/or unsaved form fields and their values to filter results for other fields dynamically. This is available for forms created via JSON view and form scripts. The user-entered, stored/unstored setting values of other fields on the form should be available to use with the handlebar expressions. Based on where the form is built, you can input the following into handlebar expressions:

  • Integration – Integration settings

  • Flow group – Integration and flow group settings

  • Flow – Integration, flow group, and flow settings

  • Export – Integration, flow group, flow, and export settings, and attached connection fields

    Note

    Encrypted values are not displayed or made available in a way that could compromise their security.

  • Import – Integration, flow group, flow, and import settings, and attached connection fields

    Note

    Encrypted values are not displayed or made available in a way that could compromise their security.

refreshOptionsOnChangesTo is used in conjunction with supportHandlebars, allowing you to define which fields should trigger another call to fetch the options dropdown.

Required

No

Format

Boolean

Values

True or False

Example

"supportHandlebars": true

 
{
  "fieldMap": {
    "company": {
      "type": "exportSelect",
      "id": "company",
      "name": "company",
      "label": "company",
      "resource": {
        "virtual": {
          "name": "Get companies",
          "_connectionId": "68c••••739",
          "asynchronous": true,
          "oneToMany": false,
          "sandbox": false,
          "http": {
            "relativeURI": "/v2.0/companies",
            "method": "GET",
            "requestMediaType": "json",
            "successMediaType": "json",
            "errorMediaType": "json",
            "_httpConnectorVersionId": "655••7f0",
            "_httpConnectorResourceId": "655••899",
            "_httpConnectorEndpointId": "655••89a",
            "isRest": false,
            "formType": "http",
            "paging": {
              "method": "url",
              "path": "[@odata.nextLink]",
              "lastPageStatusCode": 404
            },
            "response": {
              "resourcePath": "value",
              "twoDArray": {
                "doNotNormalize": false,
                "hasHeader": false
              }
            }
          },
          "transform": {
            "type": "expression",
            "expression": {
              "rules": [
                []
              ],
              "rulesTwoDotZero": {
                "mappings": [
                  {
                    "generate": "value",
                    "dataType": "string",
                    "extract": "$.id",
                    "status": "Active",
                    "sourceDataType": "string"
                  },
                  {
                    "generate": "label",
                    "dataType": "string",
                    "extract": "$.name",
                    "status": "Active",
                    "sourceDataType": "string"
                  }
                ],
                "mode": "create"
              },
              "version": "2"
            },
            "rules": [
              []
            ],
            "version": "2"
          },
          "adaptorType": "HTTPExport"
        }
      }
    },
    "customer": {
      "id": "customer",
      "name": "customer",
      "type": "exportSelect",
      "label": "customer list based on company",
      "supportHandlebars": true,
      "refreshOptionsOnChangesTo": [
        "company"
      ],
      "visibleWhen": [
        {
          "field": "company",
          "isNot": [
            null,
            ""
          ]
        }
      ],
      "resource": {
        "virtual": {
          "_id": "68c••d8e",
          "createdAt": "2025-09-10T09:41:27.512Z",
          "lastModified": "2025-09-10T09:43:48.230Z",
          "name": "Get data",
          "_connectionId": "68c••••739",
          "apiIdentifier": "eb7ad49459",
          "asynchronous": true,
          "oneToMany": false,
          "sandbox": false,
          "http": {
            "relativeURI": "/v2.0/companies({{export.company}})/customers",
            "method": "GET",
            "requestMediaType": "json",
            "successMediaType": "json",
            "errorMediaType": "json",
            "_httpConnectorVersionId": "655••7f0",
            "_httpConnectorResourceId": "655•••899",
            "_httpConnectorEndpointId": "655•••89a",
            "isRest": false,
            "formType": "http",
            "paging": {
              "method": "url",
              "path": "[@odata.nextLink]",
              "lastPageStatusCode": 404
            },
            "response": {
              "resourcePath": "value",
              "twoDArray": {
                "doNotNormalize": false,
                "hasHeader": false
              }
            }
          },
          "rawData": "677b••••fd9",
          "transform": {
            "type": "expression",
            "expression": {
              "rules": [
                []
              ],
              "rulesTwoDotZero": {
                "mappings": [
                  {
                    "generate": "value",
                    "dataType": "string",
                    "extract": "$.id",
                    "status": "Active",
                    "sourceDataType": "string"
                  },
                  {
                    "generate": "label",
                    "dataType": "string",
                    "extract": "$.displayName",
                    "status": "Active",
                    "sourceDataType": "string"
                  }
                ],
                "mode": "create"
              },
              "version": "2"
            },
            "rules": [
              []
            ],
            "version": "2"
          },
          "adaptorType": "HTTPExport"
        }
      }
    }
  }
}

touched

Required

No

Format

Boolean

Values

This automatically enables the Save button once a change is made in the custom form. By default, this is set to true , but it is usually not needed since most fields automatically handle this.

  • true

  • false

Example

"touched": true

typeAheadSearch

Use typeAheadSearch to execute a virtual export that populates new, filtered results in real-time as the user types. The list of options will adjust as users type, so the system doesn't have to fetch all the available results as the form loads. The default value is false. This field is available for the exportSelect and staticMap field types. The user's entered text must be accessible in the virtual export definition in order to correctly place where the query parameters should be passed.

Required

No

Format

Boolean

Values

  • true

  • false

Example

"typeAheadSearch": true

In the example below, the relative URI contains handlebars that pull data for the typeAheadSearch field. When working with this field, you must map the value field to the input that needs to be sent back to the relative URI.

{
  "fieldMap": {
    "searchFiles": {
      "id": "searchFiles",
      "name": "searchFiles",
      "type": "exportSelect",
      "label": "Search files",
      "typeAheadSearch": true,
      "storeAdditionalProperties": [
        "id"
      ],
      "resource": {
        "virtual": {
          "_id": "68c13f5628943b14298d6b3f",
          "createdAt": "2025-09-10T09:05:26.381Z",
          "lastModified": "2025-09-10T09:11:10.854Z",
          "name": "search files",
          "_connectionId": "677bc7c2f35362e773bc590b",
          "apiIdentifier": "e0e41b1e8b",
          "asynchronous": true,
          "oneToMany": false,
          "sandbox": false,
          "http": {
            "relativeURI": "/drive/v3/files?q=name contains '{{export.searchFiles}}'",
            "method": "GET",
            "requestMediaType": "json",
            "successMediaType": "json",
            "errorMediaType": "json",
            "_httpConnectorVersionId": "66a0a457ea5ed5b80f6efa75",
            "_httpConnectorResourceId": "66a0a58d14d3ef71f9cf599a",
            "_httpConnectorEndpointId": "66a0a58d14d3ef71f9cf59b9",
            "isRest": false,
            "formType": "http",
            "response": {
              "resourcePath": "files",
              "twoDArray": {
                "doNotNormalize": false,
                "hasHeader": false
              }
            }
          },
          "rawData": "677bc7aa97c3604199a6e16fcb72dac68838497289907d19293653d8",
          "transform": {
            "type": "expression",
            "expression": {
              "rules": [
                []
              ],
              "rulesTwoDotZero": {
                "mappings": [
                  {
                    "generate": "value",
                    "dataType": "string",
                    "extract": "$.name",
                    "status": "Active",
                    "sourceDataType": "string"
                  },
                  {
                    "generate": "label",
                    "dataType": "string",
                    "extract": "$.name",
                    "status": "Active",
                    "sourceDataType": "string"
                  },
                  {
                    "generate": "id",
                    "dataType": "string",
                    "extract": "$.id",
                    "status": "Active",
                    "sourceDataType": "string"
                  }
                ],
                "mode": "create"
              },
              "version": "2"
            },
            "rules": [
              []
            ],
            "version": "2"
          },
          "adaptorType": "HTTPExport"
        }
      }
    }
  }
}

validWhen

Applies to

Applies to Text input ("type":"text")

Required

No

Format

Object

Values

  • pattern – The pattern against which you would want to match the user input

  • message – the message you would show the user when the input doesn’t match the pattern

Example

validWhen:{
    matchesRegEx: {
        pattern: '^[a-zA-Z0-9_]+$',
        message: 'Enter only alphabets, numbers, dash, or underscore.'
        }
    }

valueName

Applies to

Key-value pairs ("type": "keyvalue")

Required

Yes

Format

String

Values

The placeholder tip that you want displayed for the value (input on the right)

Example

"valueName": "your-value"

visibleWhen

Required

No

Format

Array

Values

The visibleWhen setting controls whether the field is visible under certain conditions. The setting accepts multiple objects, each with a field key and is or isNot value arrays. A field becomes visible if any object is true, meaning a value matches any value in the is array and doesn't match any value in the isNot array.

  • 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

  • isNot – a list of possible values for the other field, which – after user interaction – will make this field visible if not true

Example 1

"visibleWhen": [
  {
    "field": "formFieldDefined",
    "is": [
      "Proposal", "Test", "Example"
      ]
},
{
    "field": "radiobutton",
    "is": [ 
      "Proposal", "Test", "Example"
    ]
  },
{
    "field": "formFieldDefined",
    "isNot": [
      "Proposal", "Test", "Example"
    ]
  }
]

Example 2

"visibleWhen": {
"id": "visibleWhen",
"name": "visibleWhen",
"type": "select",
"label": "Visible when",
"defaultValue": "Hyderabad",
"description": "This field will be visible only when radiogroup is set as create and select is set as USA or when radiogroup is set as update and select is set as Canada",
 "options": [
  {
   "items": [
     "Delhi",
     "Hyderabad",
     "Chennai"
    ]
   }
  ],
  "visibleWhen": [
   { "OR":[
     {"AND":
      [{
       "field": "radiogroup",
       "is": [
        "Create"
        ]
       },
      {
      "field": "select",
       "is": [
        "USA"
        ]
       }
      ]
     },
     {"AND":
      [{
       "field": "radiogroup",
        "is": [
         "Update"
        ]
       },{
      "field": "select",
       "is": [
        "Canada"
        ]
       }
      ]
     }
    ]
   }
  ]
 }

visibleWhenAll

Required

No

Format

Array

Values

The visibleWhenAll setting controls whether the field is visible under certain conditions. The setting accepts multiple objects, each with a field key and is or isNot value arrays. A field becomes visible if all objects are true, meaning the values match all the values in the is array, and don't match any value in the isNot array.

  • 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

  • isNot – a list of possible values for the other field, which – after user interaction – will make this field visible if not true

Examples

"visibleWhenAll": [
  {
    "field": "formFieldDefined",
    "is": [
      "Proposal", "Test", "Example"
      ]
},
{
    "field": "radiobutton",
    "is": [ 
      "Proposal", "Test", "Example"
    ]
  },
{
    "field": "formFieldDefined",
    "isNot": [
      "Proposal", "Test", "Example"
    ]
  }
]

"visibleWhenAll": {
"id": "visibleWhenAll",
"name": "visibleWhenAll",
"type": "select",
"label": "Visible when all",
"defaultValue": "Hyderabad",
"description": "This field will be visible only when radiogroup is set as create and select is set as USA or when radiogroup is set as update and select is set as Canada",
 "options": [
  {
   "items": [
     "Delhi",
     "Hyderabad",
     "Chennai"
    ]
   }
  ],
  "visibleWhenAll": [
   { "OR":[
     {"AND":
      [{
       "field": "radiogroup",
       "is": [
        "Create"
        ]
       },
      {
      "field": "select",
       "is": [
        "USA"
        ]
       }
      ]
     },
     {"AND":
      [{
       "field": "radiogroup",
        "is": [
         "Update"
        ]
       },{
      "field": "select",
       "is": [
        "Canada"
        ]
       }
      ]
     }
    ]
   }
  ]
 }

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; post in the Celigo Connective if you see a specific form field in the Celigo platform 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
360092094212-custom-forms-19.png

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
360092095192-custom-forms-20.png

Typical Custom settings response

 
{
  "disclaim": true
}

Date selector

JSON definition

 
"createdAfter": {
  "id": "createdAfter",
  "name": "createdAfter",
  "type": "date",
  "label": "Created after"
}

Resulting field
360092080691-custom-forms-30.png

Typical Custom settings response

 
{
  "createdAfter": "07/04/2020"
}

DateTime

JSON definition

 
"datetime": {
  "id": "datetime",
  "name": "datetime",
  "type": "datetime",
  "label": "Date/time",
  "doNotAllowFutureDates": true,
  "skipTimezoneConversion": true
}

Resulting field
custom_code_datetime.png

Typical Custom settings response

 
{
  "datetime": "2024-07-10T07:03:07.285Z"
}

Drop-down list

The drop-down limit for this field is 1,000. If you create a drop-down list with more than 1,000 fields, you must use a form script.

JSON definition

 
"province": {
  "id": "province",
  "name": "province",
  "type": "select",
  "label": "Province",
  "options": [
    {
      "items": [
        "Ontario",
        "Quebec",
        "Manitoba"
      ]
    }
  ]
}

Resulting field
360092081471-custom-forms-17.png

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
360092081711-custom-forms-21.png

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
360092083451-custom-forms-18.png

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
360092099372-custom-forms-16.png

Typical Custom settings response

 
{
  "pickOne": "1"
}

Remove invalid values

This value can be used only when "type": "multiselect".

If one of the options of the multi-select list is removed, but the form is already saved with that field selected, setting this to true will remove the now invalid selection from the settings object accessed in the flow.

  • true - Removes invalid values

  • false [default]

JSON definition

 
"removeInvalidValues" = true

Text input – single or multiline

JSON definition

 
"myTxtField": {
  "id": "myTxtField",
  "name": "myTxtField",
  "type": "text", 
  "label": "Reason for editing my clean export"
}

Resulting field
360092101132-custom-forms-13.png

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
360092103492-custom-forms-14.png

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
360092105272-custom-forms-15.png

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
360092092351-custom-forms-27.png

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
360092094411-custom-forms-22.png

Typical Custom settings response

 
{
  "turnOn": true
}

Type: Dynamic list

The exportSelect form field allows you to use a virtual export to retrieve export values from a source application dynamically. Using a virtual export, you can call out to a source application like NetSuite or Shopify to retrieve your selections. exportSelect also has a multi-select option. When set to true, it acts like a standard multi-select list but gets dynamic options from the virtual exports. If multi-select is set to false (default), it acts the same as a standard select list but gets dynamic options from the virtual exports.

Note

You may need to add a transformation because you must return both a value and a label for each option. For example, if we get a list of locations from Shopify, they will return a location id and name to NetSuite. We must add a transform to convert the id to value and the name to label. If you create an export in integrator.io, you’ll need to use the +Create flow option instead of the Export tab, which doesn’t have the option to create a transformation. See the transformation example for more information.

Tip

When using virtual exports within your forms, a _connectionId:

  • is not required when the form is built in exports and imports and uses the JSON form builder

  • is required

    • when built into all form scripts

    • when the form is built at the integration, flow group, or flow level

"multiselect": true

Example 1: JSON definition

 
{
  "fieldMap": {
    "exportSelect": {
      "id":"exportSelect",
      "name":"exportSelect",
      "type":"exportSelect",
      "helpText":"help text",
      "label":"label",
      "resource":{
         "virtual":{
          "name": "Lookup",
          "_connectionId": "626••••••••••••••••d7",
          "apiIdentifier": "e••••••78",
          "asynchronous": true,
          "oneToMany": false,
          "sandbox": false,
          "netsuite": {
            "type": "restlet",
            "skipGrouping": true,
            "statsOnly": false,
            "restlet": {
              "recordType": "location",
              "searchId": "2597",
              "restletVersion": "suitebundle"
            },
            "distributed": {
              "useSS2Framework": false
            }
          },
          "distributed": {
            "disabled": false
          },
          "adaptorType": "NetSuiteExport"
        }
      }
   }
  }
}

"multiselect": false

Example 1: JSON definition

 
{
  "fieldMap": {
    "exportSelect": {
      "id":"exportSelect",
      "name":"exportSelect",
      "type":"exportSelect",
      "helpText":"help text",
      "label":"label",
      "resource":{
         "virtual":{
          "name": "Lookup",
          "_connectionId": "62•••••••••••••d7",
          "asynchronous": true,
          "oneToMany": false,
          "sandbox": false,
          "netsuite": {
            "type": "restlet",
            "skipGrouping": true,
            "statsOnly": false,
            "restlet": {
              "recordType": "location",
              "searchId": "2597",
              "restletVersion": false
            },
            "distributed": {
              "useSS2Framework": false
            }
          },
          "distributed": {
            "disabled": false
          },
          "adaptorType": "NetSuiteExport"
        }
      }
   }
  }
}

JSON definition with transformation

 
{
  "fieldMap": {
    "exportSelect": {
      "id":"exportSelect",
      "name":"exportSelect",
      "type":"exportSelect",
      "helpText":"help text",
      "label":"label",
      "resource":{
         "virtual":{
          "name": "Get Locations",
          "_connectionId": "62d••••••••••••••ba6",
          "apiIdentifier": "ed••••••35",
          "asynchronous": true,
          "assistant": "shopify",
          "oneToMany": false,
          "sandbox": false,
          "assistantMetadata": {
            "resource": "locations",
            "version": "v2",
            "operation": "retrieves_alistoflocations"
          },
          "http": {
            "relativeURI": "/locations.json",
            "method": "GET",
            "successMediaType": "json",
            "errorMediaType": "json",
            "formType": "assistant",
            "paging": {
              "method": "linkheader",
              "lastPageStatusCode": 404,
              "linkHeaderRelation": "next"
            },
            "response": {
              "resourcePath": "locations"
            }
          },
          "rest": {
            "relativeURI": "/locations.json",
            "method": "GET",
            "resourcePath": "locations",
            "pagingMethod": "linkheader",
            "allowUndefinedResource": false,
            "linkHeaderRelation": "next"
          },
          "transform": {
            "type": "expression",
            "expression": {
              "rules": [
                [
                  {
                    "extract": "id",
                    "generate": "value"
                  },
                  {
                    "extract": "name",
                    "generate": "label"
                  }
                ]
              ],
              "version": "1"
            },
            "version": "1",
            "rules": [
              [
                {
                  "extract": "id",
                  "generate": "value"
                },
                {
                  "extract": "name",
                  "generate": "label"
                }
              ]
            ]
          },
          "adaptorType": "RESTExport"
        }
      }
   }
  }
}

Type: nativeField

The nativeField type accepts a new field called nativeFieldPath where you can enter the path to the native field you would like to display. When the form is saved with this field type, the value will be stored in the native field and custom settings. Setting certain common fields in the custom settings form will override the native field values. If these fields are not present in the JSON definition, the native field’s values will be used. You can override these common fields:

  • label

  • helpText

  • required

  • defaultValue

Example

 
{
  "useAsPrimaryInterface": false,
  "fieldMap": {
    "hasHeaderNativeField": {
      "id": "hasHeaderNativeField",
      "name": "hasHeaderNativeField",
      "type": "nativeField",
      "nativeFieldPath": "export.http.response.twoDArray.hasHeader",
      "helpText": "Permissions assigned to you by IT.",
      "label": "test"
    }
  },
  "layout": {
    "fields": [
      "hasHeaderNativeField",
      "name"
    ]
  }
}

Type: Refreshable drop-down list

The Refreshable drop-down list form field allows you to create a drop-down list of items, similar to the standard Select option. However, for Refreshable drop-down list, the drop-down 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. The drop-down limit for this field is 1,000. If you create a drop-down list with more than 1,000 fields, you must use a form script.

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
view.png
view_2.png

Type: Static or refreshable mapping

staticMap is a refreshable or static form field that lets you map values using virtual exports or hard-coded options. It’s similar to mapping in integrator.io’s user interface; for example, mapping a Shopify location to a NetSuite location. This form field requires a combination of two virtual exports, two hard-coded options, one virtual export and one hard-coded option on the left or right, respectively, or any combination of virtual exports and/or hard-coded values to populate the list options (requires the keyOptions field for more than 2 columns). If you want the left side of your mapping to be dynamic, you’ll need the virtual export on that side or vice versa. When using the staticMap field type, the optionsMap field will accept exportSelect field types.

Option: Using virtual exports to populate the list options

{
  "fieldMap": {
    "refreshable": {
      "id": "refreshable",
      "name": "refreshableName",
      "type": "staticMap",
      "label": "label this",
      "keyName": "extract",
      "keyLabel": "extractLabel",
      "valueName": "generate",
      "valueLabel": "generateLabel",
      "keyResource": {
        "virtual": {
          "name": "Lookup",
          "_connectionId": "626•••••••••••••••••d7",
          "apiIdentifier": "ea7••••••8",
          "asynchronous": true,
          "oneToMany": false,
          "sandbox": false,
          "netsuite": {
            "type": "restlet",
            "skipGrouping": true,
            "statsOnly": false,
            "restlet": {
              "recordType": "location",
              "searchId": "1234",
              "restletVersion": false
            },
            "distributed": {
              "useSS2Framework": false
            }
          },
          "distributed": {
            "disabled": false
          },
          "adaptorType": "NetSuiteExport"
        }
      },
      "valueResource": {
        "virtual": {
          "name": "Get Locations",
          "_connectionId": "62d•••••••••••••••••a6",
          "apiIdentifier": "ed•••••65",
          "asynchronous": true,
          "assistant": "shopify",
          "oneToMany": false,
          "sandbox": false,
          "assistantMetadata": {
            "resource": "locations",
            "version": "v2",
            "operation": "retrieves_alistoflocations"
          },
          "http": {
            "relativeURI": "/locations.json",
            "method": "GET",
            "successMediaType": "json",
            "errorMediaType": "json",
            "formType": "assistant",
            "paging": {
              "method": "linkheader",
              "lastPageStatusCode": 404,
              "linkHeaderRelation": "next"
            },
            "response": {
              "resourcePath": "locations"
            }
          },
          "rest": {
            "relativeURI": "/locations.json",
            "method": "GET",
            "resourcePath": "locations",
            "pagingMethod": "linkheader",
            "allowUndefinedResource": false,
            "linkHeaderRelation": "next"
          },
          "transform": {
            "type": "expression",
            "expression": {
              "rules": [
                [
                  {
                    "extract": "id",
                    "generate": "value"
                  },
                  {
                    "extract": "name",
                    "generate": "label"
                  }
                ]
              ],
              "version": "1"
            },
            "version": "1",
            "rules": [
              [
                {
                  "extract": "id",
                  "generate": "value"
                },
                {
                  "extract": "name",
                  "generate": "label"
                }
              ]
            ]
          },
          "adaptorType": "RESTExport"
        }
      }
    }
  }

Option: Using hard-coded values to populate the list options

  "fieldMap": {
    "refreshable": {
      "id": "refreshable",
      "name": "refreshableName",
      "type": "staticMap",
      "label": "label this",
      "keyName": "extract",
      "keyLabel": "extractLabel",
      "valueName": "generate",
      "valueLabel": "generateLabel",
      "keyOptions": [
        {
          "value": "10",
          "label": "Austin"
        },
        {
          "value": "9",
          "label": "Baltimore"
        },
        {
          "value": "1",
          "label": "California"
        },
        {
          "value": "5",
          "label": "Dallas"
        },
        {
          "value": "4",
          "label": "FBA"
        },
        {
          "value": "2",
          "label": "Florida"
        },
        {
          "value": "6",
          "label": "Houston"
        },
        {
          "value": "11",
          "label": "Indianapolis"
        },
        {
          "value": "3",
          "label": "Maryland"
        },
        {
          "value": "7",
          "label": "Memphis"
        },
        {
          "value": "8",
          "label": "San Mateo"
        }
      ],
      "valueOptions": [
        {
          "value": "67738009765",
          "label": "BOISBRIAND"
        },
        {
          "value": "67738042533",
          "label": "BOUCHERVILLE"
        },
        {
          "value": "49044553893",
          "label": "California"
        },
        {
          "value": "49920475301",
          "label": "Florida"
        }
      ]
    }
  }
}

Option: More than 2 columns in a mapping table

{
  "fieldMap": {
    "salesforceAccountType_map_netsuiteCustomerStageAndStatus": {
      "optionsMap": [
        {
          "id": "salesforceAccountType",
          "label": "Salesforce Account Type",
          "required": true,
          "type": "select",
          "options": [
            {
              "value": "prospect",
              "label": "Prospect"
            },
            {
              "value": "customer_direct",
              "label": "Customer - Direct"
            },
            {
              "value": "customer_channel",
              "label": "Customer - Channel"
            },
            {
              "value": "channel_partner_reseller",
              "label": "Channel Partner / Reseller"
            },
            {
              "value": "installation_partner",
              "label": "Installation Partner"
            },
            {
              "value": "technology_partner",
              "label": "Technology Partner"
            },
            {
              "value": "other",
              "label": "Other"
            }
          ]
        },
        {
          "id": "netsuiteCustomerStage",
          "label": "NetSuite Customer Stage",
          "required": true,
          "type": "select",
          "options": [
            {
              "value": "lead",
              "label": "Lead"
            },
            {
              "value": "prospect",
              "label": "Prospect"
            },
            {
              "value": "customer",
              "label": "Customer"
            }
          ]
        },
        {
          "id": "netsuiteCustomerStatus",
          "label": "NetSuite Customer Status",
          "required": false,
          "type": "select",
          "options": [
            {
              "value": "6",
              "label": "Unqualified"
            },
            {
              "value": "7",
              "label": "Qualified Lead"
            },
            {
              "value": "8",
              "label": "In Discussion"
            },
            {
              "value": "9",
              "label": "Identified Decision Makers"
            },
            {
              "value": "10",
              "label": "Proposal"
            },
            {
              "value": "11",
              "label": "In Negotiation"
            },
            {
              "value": "12",
              "label": "Purchasing"
            },
            {
              "value": "13",
              "label": "Closed Won"
            },
            {
              "value": "14",
              "label": "Closed Lost"
            },
            {
              "value": "15",
              "label": "Renewal"
            },
            {
              "value": "16",
              "label": "Lost Customer"
            },
            {
              "value": "17",
              "label": "Qualified Prospect"
            }
          ]
        }
      ],
      "allowFailures": false,
      "hideLookupAllowFailures": true,
      "title": "Map Salesforce Account Type to NetSuite Customer Stage and Status",
      "tooltip": "",
      "name": "salesforceAccountType_map_netsuiteCustomerStageAndStatus",
      "type": "staticMap"
    }
  }
}
image (26).png

URL input

JSON definition

 
"productsUrl": {
  "id": "productsUrl",
  "name": "productsUrl",
  "type": "relativeuri",
  "label": "URL for exporting products"
}

Resulting field
360092110952-custom-forms-26.png

Typical Custom settings response

 
{
  "productsUrl": "prod/v1/"
}

Form layout option

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"
    ]
  }
}
360092227892-custom-forms-23.png

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"
        ]
      }
    ]
  }
}
360092214631-custom-forms-24.png

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"
        ]
      }
    ]
  }
}
360092217751-custom-forms-25.png

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"
        ]
      }
    ]
  }
}
360092244332-custom-forms-28.png

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"
        ]
      }
    ]
  }
}
360092228571-custom-forms-29.png

Organize form fields into tabbed sections (horizontal)

The layout object includes a "type": "tabWithoutSave" option that organizes referenced fields into horizontal tabbed sections. You can then label and order the fields within each section by defining them as items in the containers object.

The example below illustrates how to define two horizontal tabs:

{
  "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?"
    },
    "email": {
      "id": "email",
      "name": "email",
      "type": "text",
      "label": "What is your email?"
    },
    "address": {
      "id": "address",
      "name": "address",
      "type": "text",
      "label": "Address?"
    }
  },
  "layout": {
    "type": "tabWithoutSave",
    "containers": [
      {
        "collapsed": false,
        "label": "General",
        "fields": [
          "firstName",
          "lastName"
        ]
      },
      {
        "collapsed": false,
        "label": "Advanced",
        "fields": [
          "email",
          "address"
        ]
      }
    ]
  }
}
Horizontal_tab.png

Organize form fields into tabbed sections (vertical)

The layout object includes a "type": "verticalTabWithoutSave" option that organizes referenced fields into vertical tabbed sections. You can then label and order the fields within each section by defining them as items in the containers object.

The example below illustrates how to define two vertical tabs:

{
  "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?"
    },
    "email": {
      "id": "email",
      "name": "email",
      "type": "text",
      "label": "What is your email?"
    },
    "address": {
      "id": "address",
      "name": "address",
      "type": "text",
      "label": "Address?"
    }
  },
  "layout": {
    "type": "verticalTabWithoutSave",
    "containers": [
      {
        "collapsed": false,
        "label": "General",
        "fields": [
          "firstName",
          "lastName"
        ]
      },
      {
        "collapsed": false,
        "label": "Advanced",
        "fields": [
          "email",
          "address"
        ]
      }
    ]
  }
}
vertical_tab.png

Customize your form

Use the useAsPrimaryInterface boolean field in a custom form to customize the primary interface of workflow bubbles. This feature ensures that only crucial settings are displayed prominently, while other sections are concealed to reduce clutter. To capture necessary user inputs, include any relevant fields directly in the custom form. The Custom settings section was renamed to Settings and is available directly below the General section for better accessibility. These changes apply to all bubbles, including listeners. When this setting is enabled, the following sections are visible:

  • [Custom] Settings

  • Mock output (exports)

  • Mock response (imports)

  • Advanced (exports and imports)

Screenshot_2024-04-16_at_18_14_08.png

JSON definition

Below is the JSON definition:

{
"useAsPrimaryInterface": true
...
}