Common form fields – Celigo Help Center

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.

Tip: 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.

Required and optional form field settings
Available fields
Form layout options

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` `name` `type`	`defaultValue` `delimiter` `description` `helpText` `inputType` `keyName`	`label` `mode` `multiline` `options` (simple set) `options` (arrays of labels and values)	`required` `rowsMax` `showDelete` `valueName` `visibleWhen`

`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: `"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 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	`csv` `text` `xml` `json`
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 Checkbox Date selector Drop-down list	Key-value pairs Multi-select list Radio buttons Text input – single or multiline Text input – delimited	Text input – number Text input – password Toggle switch Type: Refreshable dropdown list URL input

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:

The order of the form fields
Column distribution
Organized fields into sections:

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

Bas van Ditzhuijzen Strategic Partner NetSuite Integration Whiz Salesforce Integration Whiz

February 17, 2023 08:45
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
0

Bas van Ditzhuijzen Strategic Partner NetSuite Integration Whiz Salesforce Integration Whiz

February 17, 2023 08:52

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.

"CeligoFileDefinitionId": {
      "helpText": "The Id",
      "id": "CeligoFileDefinitionId",
      "label": "Celigo File Definition Id",
      "name": "CeligoFileDefinitionId",
      "required": true,
      "resource": {
        "virtual": {
          "_connectionId": "yourconnectionId",
          "adaptorType": "HTTPExport",
          "asynchronous": true,
          "http": {
            "errorMediaType": "json",
            "formType": "rest",
            "method": "GET",
            "relativeURI": "/v1/filedefinitions",
            "successMediaType": "json"
          },
          "name": "read file definitions",
          "oneToMany": false,
          "transform": {
            "expression": {
              "rules": [
                [
                  {
                    "extract": "_id",
                    "generate": "value"
                  },
                  {
                    "extract": "name",
                    "generate": "label"
                  }
                ]
              ],
              "version": "1"
            },
            "rules": [
              [
                {
                  "extract": "_id",
                  "generate": "value"
                },
                {
                  "extract": "name",
                  "generate": "label"
                }
              ]
            ],
            "type": "expression",
            "version": "1"
          }
        }
      },
      "type": "exportSelect"
    }

Tyler Lamparter Senior Solutions Consultant

February 17, 2023 19:01

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!

"CeligoFileDefinitionId": {
      "helpText": "The Id",
      "id": "CeligoFileDefinitionId",
      "label": "Celigo File Definition Id",
      "name": "CeligoFileDefinitionId",
      "required": true,
      "multiselect": true,
      "resource": {
        "virtual": {
          "_connectionId": "yourconnectionId",
          "adaptorType": "HTTPExport",
          "asynchronous": true,
          "http": {
            "errorMediaType": "json",
            "formType": "rest",
            "method": "GET",
            "relativeURI": "/v1/filedefinitions",
            "successMediaType": "json"
          },
          "name": "read file definitions",
          "oneToMany": false,
          "transform": {
            "expression": {
              "rules": [
                [
                  {
                    "extract": "_id",
                    "generate": "value"
                  },
                  {
                    "extract": "name",
                    "generate": "label"
                  }
                ]
              ],
              "version": "1"
            },
            "rules": [
              [
                {
                  "extract": "_id",
                  "generate": "value"
                },
                {
                  "extract": "name",
                  "generate": "label"
                }
              ]
            ],
            "type": "expression",
            "version": "1"
          }
        }
      },
      "type": "exportSelect"
    }

Please sign in to leave a comment.

Contents

Required and optional form field settings

id

name

type

label

helpText

description

required

inputType

multiline

rowsMax

defaultValue

delimiter

options (simple set)

options (arrays of labels and values)

mode

keyName

valueName

showDelete

visibleWhen

Available fields

Advanced field editor

Checkbox

Date selector

Drop-down list

Key-value pairs

Multi-select list

Radio buttons

Text input – single or multiline

Text input – delimited

Text input – number

Text input – password

Toggle switch

Type: Refreshable drop-down list

URL input

Form layout options

Specify the order of custom form fields

Establish a multi-column layout

Organize form fields into collapsible sections

Organize form fields into boxed sections

Organize form fields into indented sections

Related articles

`id`

`name`

`type`

`label`

`helpText`

`description`

`required`

`inputType`

`multiline`

`rowsMax`

`defaultValue`

`delimiter`

`options` (simple set)

`options` (arrays of labels and values)

`mode`

`keyName`

`valueName`

`showDelete`

`visibleWhen`