Articles in this section

Create custom settings & access them in integrator.io forms

Stephen Brandt
Updated

Custom settings allow you to define additional attributes on resources that can then be accessed within the logic of your flows.

Custom forms allow users of your resources to control the values of these custom settings in convenient forms that can be extended with scripts. Custom forms give less technical users the ability to easily configure flows to suit their needs.

Defining custom settings

You can define custom settings for the following resource types:

  • Integrations, via the Settings tab

  • Flows, via the settings_gear.svg​ Settings pane

  • Connections, exports, and imports, via the Custom settings section of their respective forms

Settings can be defined only for resources to which you have Manager (write) access. Once settings are defined and a custom form is built for those settings, then any user with Manager access can modify the values for those settings.

Specify simple custom settings

You can define settings by entering valid JSON objects into the Settings editor. In this example, we are introducing two fields to the settings of an integration:

custom-forms-1.png

Similarly, in this example, we are adding a field to a flow within an integration:

custom-forms-2b.png

Using custom settings in flows

As mentioned above, integrator.io allows you to define settings for all of the key resource types. The settings on each resource are independent, which means that – for example – the settings on a flow can’t be defined in terms of the integration that the connection is used in.

Scope of settings

Custom settings are available for each integration and its resources: flow, connections, exports, and imports. Because of the relationship between these objects, custom settings are cumulative, and integrator.io makes it easy for you to access settings from the various scopes.

For example, when working on a hook for an export in a flow, you will have access to the settings for:

  • The export itself;

  • The flow the export is a part of;

  • The connection that the flow uses; and

  • The integration that the flow belongs to

Where available, you will find settings as an object at the same level as the actual flow record data itself. For example, to continue the example from the previous section, notice the settings object below and the way in which the individual integration and flow setting attributes appear within it:

360061156192-custom-forms-3.png

Using settings to change flow behavior

Once you have defined settings, you can use them to change the behavior of your flows. You can currently access the settings object in filters, transforms, and hooks.

  • Filters: the settings object is available in both the rules and script-based filter. In the rules-based view, notice that all settings appear in the drop-down list for the second operand.

360061157852-custom-forms-4a.png

  • Transforms: the settings object is available only in the script-based transform, which means you can refer to elements of the settings object using the regular JavaScript dot notation.

  • Hooks: the settings object is available, at present, in most hooks.

Using settings in mappings

Custom settings are currently not available for import mapping and response mapping. In order to work around this limitation, we recommend you copy any settings that you would like to use in mapping into the flow data itself before the mapping step, ideally as part of a preMap hook.

In this example, we are copying the region attribute from the flow settings back into the data so that it can be used in the mapping step:

360061158952-custom-forms-5.png