dataSourceConfigVar()

Creates a data source-backed config variable for code-native integrations.

The dataSourceConfigVar() function defines a config variable whose values are dynamically populated by a data source — either an inline data source function or a reference to a data source in a registered component. This is useful for config variables whose valid values depend on the customer’s account data (e.g., a list of available projects, channels, or mailboxes).

A data source config var can be defined in two ways:

• Data source definition — an inline function with a perform handler that fetches and returns values dynamically.
• Data source reference — a reference to a data source action defined in a component from the componentRegistry.

Function signature

export const dataSourceConfigVar = <TDataSourceConfigVar extends DataSourceConfigVar>(
  definition: TDataSourceConfigVar,
): TDataSourceConfigVar

Parameters

definition · DataSourceConfigVar · required

An object describing the data source config variable.

Hide Common fields

stableKey · string · required

A unique, unchanging identifier for this config variable.

dataSourceType · DataSourceType · required

The type of data returned by the data source. This determines the UI control rendered for the config variable.

Value	Description
"picklist"	Returns a list of selectable string values
"objectSelection"	Returns a list of selectable objects
"objectFieldMap"	Returns a field mapping structure
"jsonForm"	Returns a JSON Form schema and UI schema
"string"	Returns a single string value

description · string

Human-readable description for this config variable.

collectionType · 'valuelist' | 'keyvaluelist'

When set, the data source returns a collection of values. Available only for collection-compatible data source types.

permissionAndVisibilityType · 'customer' | 'embedded' | 'organization' · default: "customer"

Controls who can view and edit this config variable.

visibleToOrgDeployer · boolean · default: "true"

Whether this config variable is visible to an organization deployer.

Show Data source definition fields (inline function)

perform · DataSourcePerformFunction · required

An async function that fetches and returns data for this config variable. Called whenever the config wizard loads or refreshes this variable.

The function receives (context, params) and must return an object matching the dataSourceType:

• picklist → { result: PickList }
• objectSelection → { result: ObjectSelection }
• objectFieldMap → { result: ObjectFieldMap }
• jsonForm → { result: JSONForm }

inputs · Record<string, InputFieldDefinition>

Input fields for the data source function, similar to action inputs.

validationMode · ValidationMode

Validation mode for dataSourceType: "jsonForm" data source config variables.

dataSourceReset · DataSourceReset

Determines when the data source should reset when dependent config variables change.

Show DataSourceReset fields

mode · 'prompt' | 'always' · required

• "prompt" — Ask the user to reset when a dependency changes.
• "always" — Automatically reset when a dependency changes.

dependencies · string[]

Names of config variables that should trigger a reset when changed.

Show Data source reference fields (component data source)

dataSource · ComponentReference · required

A reference to a data source defined in a component from the componentRegistry. Includes the component key, data source key, and input values.

Show dataSource fields

component · string · required

The key of the component.

key · string · required

The key of the data source within the component.

values · object

Input values for the data source, each as a ValueExpression, ConfigVarExpression, or TemplateExpression.

validationMode · ValidationMode

Validation mode for JSON Form data sources.

dataSourceReset · Omit<DataSourceReset, 'dependencies'>

Reset configuration for this data source reference. Only mode is available (no dependencies).

Return type

dataSourceConfigVar · TDataSourceConfigVar

The same data source config variable definition object passed in, unchanged. Used for type inference.

When using a data source reference backed by a component connection, the data source can automatically use a connection config variable from the same config page by passing a ConfigVarExpression as an input value.

Examples

Inline picklist data source

import {
  configPage,
  connectionConfigVar,
  dataSourceConfigVar,
} from "@prismatic-io/spectral";

const settingsPage = configPage({
  tagline: "Configure sync settings",
  elements: {
    "Acme Connection": connectionConfigVar({
      stableKey: "acme-connection",
      dataType: "connection",
      inputs: {
        apiKey: {
          label: "API Key",
          type: "password",
          required: true,
          clean: (v) => String(v),
        },
      },
    }),
    "Target Project": dataSourceConfigVar({
      stableKey: "target-project",
      dataSourceType: "picklist",
      description: "Select the project to sync to.",
      perform: async (context, params) => {
        const connection = context.configVars["Acme Connection"];
        const apiKey = connection.fields["apiKey"];
        const response = await fetch("https://api.acme.com/projects", {
          headers: { Authorization: `Bearer ${apiKey}` },
        });
        const projects = await response.json();
        return {
          result: projects.map((p: { id: string; name: string }) => ({
            label: p.name,
            value: p.id,
          })),
        };
      },
    }),
  },
});

Related

• configPage() — The page that contains this data source config variable.
• configVar() — For static config variables that don’t require a data source.
• connectionConfigVar() — For connection config variables.
• componentManifest() — Register components whose data sources can be referenced.