Add dynamic fields and groups
Builders can use helper flows to populate a card's inputs and outputs dynamically either when a request to an API is needed to retrieve a list of fields, or when the available list of fields changes based on those Options a user selects on a card.
Connector Builder allows for two types of Dynamic Fields. Each requires a slightly different JSON structure, and the platform will recognize the intended type based on this structure when the helper flow is selected.
- Dynamic fields with static group properties
-
-
In this version of Dynamic Fields, a helper flow returns a list of fields and field properties. The group name and extensibility option (group properties) are statically added to the I/O modals.
-
- Dynamic fields with dynamic group properties
-
-
In this version of Dynamic Fields, a helper flow returns the group name and extensibility option (group properties) along with a list of fields and field properties. Use this option when either the group name or extensibility option may change based on the options a user selects on a card.
Currently, only one dynamic group is allowed for inputs, and dynamic groups can't be used for outputs.
-
To use Dynamic Fields:
- Either click Add Inputs on an Connector Action card or click Add Outputs on an action flow's Return Outputs card.
- Click Add Group and select Dynamic Input Group or Dynamic Output Group.
- Click Choose Flow to select the helper flow that creates the list of fields or fields and group properties.
Dynamic Fields with static group properties
Connector Builder expects a predefined set of keys when using Dynamic Fields:
| Key | Definition | Values | Type | Required |
|---|---|---|---|---|
| name |
The key for your field. If no displayname is provided, this is what the card user will see. |
Any text value | Text | Yes |
| displayname | The label for the field. | Any string value | Text | No |
| required |
Whether or not the card user will be required to provide a value. *only available for Inputs . |
|
True/False | No |
| type |
The data type of the field. |
|
Text | Yes |
| defaultValue |
A seeded value for the input. When left unspecified users will see the platform default values depending on the field type. |
|
|
No |
| available | A list of field types the card user can select from |
|
List of text | No |
| collection | Represented in the product as a 'List of' or an array. |
|
True/False | No |
| choices | A list of available options for the dropdown. Note that this requires the type to be Option. |
Any text value |
List (array) | No |
| attributes | If the field is of type Object, then keys on that object can be defined using the attributes key. |
List of objects |
List (array) | No |
The following is an example of a JSON object that returns four fields: a Text field, a Number field, a List of Objects with three defined keys, and an Option (dropdown) field with three choices. Note that the structure for Dynamic Fields with static group properties is an array (list) of objects:
[
{
"name":"field-1",
"displayname":"Field 1",
"type":"Text",
"defaultValue":"Hello world!",
"collection":false,
"required":true
},
{
"name":"field-2",
"displayname":"Field 2",
"type":"Number",
"collection":false,
"Required":false,
"available":[
"Text",
"Number"
]
},
{
"name":"field-3",
"displayname":"Field 3",
"type":"Object",
"collection":true,
"required":true,
"attributes":[
{
"name":"key1",
"displayname":"Key 1",
"collection":true,
"type":"Text"
},
{
"name":"key2",
"displayname":"Key 2",
"collection":false,
"type":"Number"
},
{
"name":"key3",
"displayname":"Key 3",
"collection":false,
"type":"True/False"
}
]
},
{
"name":"field-4",
"displayname":"Field 4",
"type":"Option",
"collection":false,
"required":true,
"choices":[
"Choice 1",
"Choice 2",
"Choice 3"
]
}
]
Dynamic Fields with dynamic group properties
Connector Builder expects three additional keys when using Dynamic Fields with dynamic group properties.
| Key | Definition | Values | Type | Req'd |
|---|---|---|---|---|
| name |
The group name used to categorize inputs on the connector card. |
Any string value | String | Yes |
| fields | The list of fields to display to the end users | List of objects | List (array) | Yes |
| extensible | Setting to true allows the card user to add additional fields to a card that can be processed within a connector action. |
|
Boolean | No |
The following is an example of a JSON array that returns dynamic group properties and four fields: a Text field, a Number field, a List of Objects with four defined keys, and an Option dropdown field with three choices. Note that the structure for Dynamic Fields JSON with dynamic group properties is an object with three top-level attributes:
{
"name":"Group Name",
"extensible":false,
"fields":[
{
"name":"field-1",
"displayname":"Field 1",
"type":"Text",
"defaultValue":"Hello world!",
"collection":false,
"required":true
},
{
"name":"field-2",
"displayname":"Field 2",
"type":"Number",
"collection":false,
"Required":false,
"available":[
"Text",
"Number"
]
},
{
"name":"field-3",
"displayname":"Field 3",
"type":"Object",
"collection":true,
"required":true,
"attributes":[
{
"name":"key1",
"displayname":"Key 1",
"collection":true,
"type":"Text"
},
{
"name":"key2",
"displayname":"Key 2",
"collection":false,
"type":"Number"
},
{
"name":"key3",
"displayname":"Key 3",
"collection":false,
"type":"True/False"
},
{
"name":"key4",
"displayname":"Key 4",
"collection":false,
"type":"Object",
"attributes": [
"name":"key4subkey1",
"displayname":"Subkey 1",
"collection":false,
"type":"Text"
]
},
]
},
{
"name":"field-4",
"displayname":"Field 4",
"type":"Option",
"collection":false,
"required":true,
"choices":[
"Choice 1",
"Choice 2",
"Choice 3"
]
}
]
}