Script Settings

Documentation for script settings and configuration using input.config()

The input.config() method allows you to define settings and inputs for your NocoDB script, creating a configuration form that appears when users run the script. This feature enables you to create reusable, configurable scripts with a friendly user interface.

Overview

When you use input.config() at the beginning of your script, NocoDB generates a settings form based on your configuration. This form is displayed to users before the script runs, allowing them to:

• Enter text values
• Select options from dropdowns
• Choose tables, views, and fields
• Provide numeric inputs
• Configure other script-specific settings

The values entered by users are returned as an object that you can use throughout your script.

Basic Usage

// Define script settings
const config = input.config({
  title: "My Script",
  description: "This script processes data based on your configuration.",
  items: [
    input.config.table('sourceTable', {
      label: 'Source Table',
      description: 'Select the table containing your source data'
    }),
    input.config.text('prefix', {
      label: 'Record Prefix',
      description: 'Prefix to add to processed record names'
    }),
    input.config.number('limit', {
      label: 'Processing Limit',
      description: 'Maximum number of records to process'
    })
  ]
});

// Use the configured values
const table = base.getTable(config.sourceTable);
const prefix = config.prefix;
const limit = config.limit;

output.text(`Using table: ${table.name}`);
output.text(`Using prefix: ${prefix}`);
output.text(`Processing limit: ${limit}`);

// Rest of your script...

Configuration Options

Main Configuration Object

The input.config() method accepts a configuration object with the following properties:

Configuration Item Types

The input.config object provides several methods for creating different types of configuration items:

input.config.table()

Creates a table selector in the settings form.

Parameters:

• key (string ): Unique identifier for this setting
• options (optional): Object with additional options:
  • label (string ): Display label for the setting
  • description (string ): Description text explaining the setting
  • default (string ): Default table ID to pre-select

Example:

input.config.table('contactsTable', {
  label: 'Contacts Table',
  description: 'Select the table containing your contacts',
  default: 'tbl_abc123' // Optional: pre-select a table by ID
})

input.config.view()

Creates a view selector in the settings form (requires a parentTable to be defined first).

Parameters:

• key (string ): Unique identifier for this setting
• options : Object with the following properties:
  • label (string ): Display label for the setting
  • description (string ): Description text explaining the setting
  • parentTable (string ): The key of a previously defined table setting
  • default (string ): Default view ID to pre-select

Example:

input.config.view('activeContactsView', {
  label: 'Active Contacts View',
  description: 'Select the view containing active contacts only',
  parentTable: 'contactsTable', // References a previously defined table setting
  default: 'vw_xyz789' // Optional: pre-select a view by ID
})

input.config.field()

Creates a field selector in the settings form (requires a parentTable to be defined first).

Parameters:

• key (string ): Unique identifier for this setting
• options : Object with the following properties:
  • label (string ): Display label for the setting
  • description (string ): Description text explaining the setting
  • parentTable (string ): The key of a previously defined table setting
  • default (string ): Default field ID to pre-select

Example:

input.config.field('emailField', {
  label: 'Email Field',
  description: 'Select the field containing email addresses',
  parentTable: 'contactsTable', // References a previously defined table setting
  default: 'fld_email456' // Optional: pre-select a field by ID
})

input.config.text()

Creates a text input in the settings form.

Parameters:

• key (string ): Unique identifier for this setting
• options (optional): Object with additional options:
  • label (string ): Display label for the setting
  • description (string ): Description text explaining the setting
  • default (string ): Default text value to pre-fill

Example:

input.config.text('emailSubject', {
  label: 'Email Subject',
  description: 'Subject line for the email notification',
  default: 'Weekly Report' // Optional: pre-fill with default text
})

input.config.select()

Creates a dropdown select menu in the settings form.

Parameters:

• key (string ): Unique identifier for this setting
• options : Object with the following properties:
  • label (string ): Display label for the setting
  • description (string ): Description text explaining the setting
  • options (Array<{value: string, label?: string}> ): Array of options for the dropdown
  • default (string ): Default option value to pre-select (must be one of the defined option values)

Example:

input.config.select('priority', {
  label: 'Task Priority',
  description: 'Select the priority level for the tasks',
  options: [
    { value: 'high', label: 'High Priority' },
    { value: 'medium', label: 'Medium Priority' },
    { value: 'low', label: 'Low Priority' }
  ],
  default: 'medium' // Optional: pre-select 'Medium Priority'
})

input.config.number()

Creates a numeric input in the settings form.

Parameters:

• key (string ): Unique identifier for this setting
• options (optional): Object with additional options:
  • label (string ): Display label for the setting
  • description (string ): Description text explaining the setting
  • default (number ): Default number value to pre-fill

Example:

input.config.number('daysAhead', {
  label: 'Days Ahead',
  description: 'Number of days to look ahead in the schedule',
  default: 7 // Optional: pre-fill with default number
})

Best Practices

1. Order matters - Place related items together, and make sure dependent fields (like views or fields that depend on a table selection) appear after their parent items.

2. Provide clear labels and descriptions - Use descriptive labels and helpful descriptions to guide users in making the right choices.

3. Use select inputs for constrained choices - When there's a fixed set of options, use input.config.select() rather than free-form text input.

4. Validate configuration - Check that all required configuration values are present and valid before proceeding with your script.

5. Keep it simple - Don't overwhelm users with too many options. Focus on the essential configuration needed for your script.

6. Test with different configurations - Make sure your script works correctly with various combinations of settings.

Limitations

1. Limited input types - Only the input types described above are supported. For more complex inputs, you may need to use the interactive input methods after the script starts.

2. Order dependency - When using dependent fields (like a view that depends on a table), the parent must be defined first.

Related

• Input
• Base
• Table
• Field

Related pages

• Base : Documentation for the base object in NocoDB Scripts
• Cursor : Documentation for the Cursor object in NocoDB Scripts
• Table : Documentation for the Table object in NocoDB Scripts
• View : Documentation for the View object in NocoDB Scripts
• Field : Documentation for the Field object and Field Types in NocoDB Scripts
• RecordQueryResult : Documentation for the RecordQueryResult object in NocoDB Scripts
• Record : Documentation for the NocoDBRecord object in NocoDB Scripts
• Session : Documentation for the Session object in NocoDB Scripts