Articles in this section

Populate a form field from a connector using a virtual export

A custom settings form can pull its options from a connected application at the moment the form loads, instead of using a hard-coded list. You do this with a formInit hook that calls exports.runVirtual() — the export is defined in your script, runs against an existing connection, and returns live data you use to build the field's options.

Use this approach when a settings field needs more than 100 options, when the options should reflect current data in the source application, or when you'd otherwise have to maintain a saved search or a saved export solely to feed one form field.

Prerequisites:

  • A connection to the source application. The virtual export runs against it, so you need its ID. See Retrieve the resource ID.
  • A custom settings form to add the field to. See Create forms.

How it works

The formInit hook runs when integrator.io loads the settings form. Inside it, your script builds the form definition in code, calls a virtual export to fetch the data, and returns the completed form. Because the export is virtual, you don't create or maintain a separate export resource — the definition lives in the script.

Calling the connector this way also avoids the 100-record limit that applies to a standard select field, and the call is asynchronous, so fetching the data doesn't block the form from loading.

Build the script

The script does four things: imports the exports object and stores the connection ID, defines a staticMap field — a key-value list — named netSuiteAccountMapping inside a formInit function, calls a second function that runs the virtual export, and pushes the returned options onto the field before adding it to the form layout.

import { exports } from 'integrator-api';

const NETSUITE_CONNECTION_ID = '612••••••••••5e7';

function formInit(options) {
  
  let form = { fieldMap: {}, layout: { fields: [] } };

  let netSuiteAccountMapping = {
    id: "netSuiteAccountMapping",
    name: "netSuiteAccountMapping",
    label: "Netsuite Account Mapping",
    type: "staticMap",
    keyName: "AccountReference",
    keyLabel: "Account Reference",
    valueName:  "NetsuiteAccount",
    valueLabel:  "Netsuite Account",
    keyOptions: [],
    valueOptions: []
  }

  let netsuiteAccounts = getNetsuiteAccounts();
  console.log('Netsuite: ' + JSON.stringify(netsuiteAccounts))
  for (let m of netsuiteAccounts) {
    netSuiteAccountMapping.valueOptions.push(m);
  }

  form.fieldMap.netSuiteAccountMapping = netSuiteAccountMapping;
  form.layout.fields.push('netSuiteAccountMapping');

  options.resource.settingsForm.form = form;
  return options.resource.settingsForm.form;
}
  

function getNetsuiteAccounts() {
    return exports.runVirtual({
      "export": {
        "name": "Get Netsuite GL Accounts",
        "_connectionId": NETSUITE_CONNECTION_ID,
        "asynchronous": true,
        "netsuite": {
            "restlet": {
              "recordType": "account",
              "useSS2Restlets": false,
              "criteria": [
                {
                  "field": "isinactive",
                  "operator": "is",
                  "searchValue": "F"
                }
              ],
              "columns": [
                {
                  "name": "name",
                  "label": "label"
                },
                {
                  "name": "internalid",
                  "label": "value"
                }
              ]
            },
            "type": "restlet",
            "skipGrouping": true,
            "statsOnly": false
          }
      }
    }).data;
  }

What the virtual export returns

In this example, getNetsuiteAccounts() queries NetSuite accounts through a RESTlet call and filters to active accounts only, using the criterion isinactive is F. For each account it retrieves two columns:

  • internalid, labeled value — becomes the stored value of each option.
  • name, labeled label — becomes the text shown to the person using the form.

The script builds the search criteria directly in JavaScript, so you don't need a saved search in NetSuite.

Adapt this to another application

The pattern — define a virtual export, run it in formInit, map the results to field options — isn't specific to NetSuite. To use a different connector, replace the connection ID and the adaptor-specific block (netsuite in this example) with the configuration for that application, and adjust which returned fields you map to the option label and value.

To find the correct configuration for another adaptor, create the export in the UI first and retrieve its JSON definition. See Build an export definition for a script.

For field definitions that call a virtual export without a formInit hook, see the exportSelect and staticMap field types in Common form fields.