While working in integrator.io with at least Manager access in Developer mode, you will see Settings within integrations, flows, connections, exports, and imports:
Example settings: 1) integration level, 2) flow level, and 3) connection level
These settings serve two complementary functions: allowing data to persist among integration objects and defining form settings (also known as form elements, controls, fields, and inputs). Within a form, you can prompt a user for information, make changes based on those selections, and capture the results after the form is submitted.
Other users of this account will be able to see the settings defined in the forms, but they will not be able to edit the definitions for a form or settings unless they have at least Manager permissions.
Advanced integrator.io features also allow you to write JavaScript to customize the form content shown during integration installation or editing – and then make decisions based on the settings during flow runtime. For example, you could...
-
Place code in hooks to retrieve data for populating form fields or basing logic on the custom settings returned
-
Author installation forms for Integration Apps
-
Handle values passed in load (formInit) or save (preSavePage) events
In just a few steps, you can add settings to your integration:
You will then be able to access the selected values throughout the integration to make flow decisions at runtime:
-
Expand the Custom settings section.
-
Click Launch form builder.
Form builder opens with placeholder JSON or any changes you had earlier saved. Let’s look at the basic elements of Form builder with a simple drop-down list added to a connection pane:
-
JSON/Script: Toggle between the default JSON view (shown above) and the advanced Script view. When you click Script, the Form definition is expanded, as described in the Script example, below.
-
Form definition: Build the JSON definition for each custom form field within fieldMap . For available form fields, layouts, and options, Common form fields.
-
Form preview: Your form definition is displayed as working form fields that will later appear in the Custom settings section of this form. Click Test form to see the…
-
Form output: The results of the user’s interaction are shown as JSON custom settings.
-
Preview/Auto preview: Click Auto preview to see the Form preview take shape as you type the Form definition. If you uncheck Auto preview, click the Preview button to make spot checks.
-
Error (not shown): Any JSON parsing or JavaScript syntax errors are listed, along with their location in your code.
Before you commit changes to an integration shared with others, you have the chance to view your form in Dev playground. Here, too, you must have Developer mode enabled, and then you can try out various form field options, based on sample JSON definitions. To get started,
-
From the Tools menu, select Dev playground.
-
Under Editor examples, expand the Form builder options.
-
Choose your sample data:
-
Simple form: A custom form definition with three fields and built-in hide/show logic depending on selection
-
Multi-column: A custom form definition that illustrates advanced layout
-
Field containers: A custom form definition with fields grouped in available layouts
-
Field dictionary: A lengthy custom form definition with the most common fields and options
-
The selected JSON opens up in a Form builder panel nearly identical to the one shown above, without the option to save. Personalize the JSON and any needed script, and make sure to copy your final version to a text file or the intended Custom [settings] section when you’re happy with the output shown.
Continuing with the simple sample above, let’s look at the JSON form definition:
{
"fieldMap": {
"RolePrompt": {
"id": "RolePrompt",
"name": "RolePrompt",
"type": "select",
"options": [
{
"items": [
"Admin",
"User",
"Monitor"
]
}
],
"label": "What is your role within this organization?",
"helpText": "Permissions assigned to you by IT.",
"required": true
}
},
"layout": {
"fields": [
"RolePrompt"
]
}
}
First of all, the fields displayed must be children of fieldMap . In this case, the field defines a drop-down list, internally called RolePrompt. That’s apparent from the following descriptive fields:
-
id (string, required): Typically the same as the object key, RolePrompt, in this case.
-
name (string, required): In most cases, the same as the id , or RolePrompt, here. The name and id are never displayed in the form.
-
type (string, required): A supported category of form fields. Enter "select" to create a drop-down list (known to HTML developers as a <select> tag).
When building a drop-down list, the choices are filled with an array of options.items , as demonstrated above. They are then sorted alphabetically in the resulting form field, and the empty default state is Please select.
Additional optional fields let you further refine the appearance of this drop-down list, such as...
-
label (string): Provide an introductory prompt for this field – such as “What is your role within this organization?”
-
required (Boolean): Not required by default. A required field – set to true – has these characteristics:
-
The label appears in boldface text.
-
It is followed by an asterisk (*).
-
Its container – when you place the field inside of a collapsible section – is expanded by default.
-
A selection is validated within the form, meaning that the submit buttons (such as Save) are disabled if nothing is selected; or, if it remains empty after interacting with the field, the user is alerted to provide input.
-
-
helpText (string, HTML tags allowed): When you enter additional instructions for this field, the help (?) button shows the content when clicked.
Note
Though the layout object is optional and has no effect in this example, it’s included here for scripting access, below.
Opening this form again in Form builder, this time we’ll toggle the Script option at the upper right:
Notice the immediate changes:
-
Form definition becomes Script input, where you can also edit the JSON
-
fieldMap.RolePrompt is now displayed as a child of resource.settingsForm.form
-
The script editor (lower left) lets you start coding or select an existing script and entry function
For demonstration purposes, we’ll make changes to the current field and also add a new field when the form is initialized, with the following function:
1 function formInit(options){
2 let form = options.resource.settingsForm.form;
3
4 // If form doesn't exist, add an empty one
5 if (!form) form = {fieldMap:{}, layout:{fields:[]}};
6
7 form.fieldMap.newBox = {
8 id: "newBox"
9 name: "newBox",
10 type: "checkbox",
11 label: "CTO notified"
12 };
13 form.layout.fields.push('newBox');
14
15 form.fieldMap.RolePrompt.label = "Select a security level";
16 form.fieldMap.RolePrompt.required = false;
17 return form;
18 }
Viewing the preview, notice the following runtime changes as soon as the form is initialized:
-
The drop-down list’s label changes (line 15)
-
The drop-down list is no longer required (line 16)
-
A new field is defined (lines 7 – 12) and added to the custom form (line 13)
Comments
Please sign in to leave a comment.