dataSource

The dataSource function creates a data source object that fetches data from an external API and returns it in a format suitable for rendering in an integration config wizard. Data sources power dynamic dropdowns, object selectors, field mappers, and JSON forms.

Function signature

function dataSource<
  TInputs extends Inputs,
  TConfigVars extends ConfigVarResultCollection,
  TDataSourceType extends DataSourceType,
>(
  definition: DataSourceDefinition<TInputs, TConfigVars, TDataSourceType>
): DataSourceDefinition<TInputs, TConfigVars, TDataSourceType>

Parameters

definition

DataSourceDefinition

required

An object describing the data source. See fields below.

`DataSourceDefinition` fields

definition.display

ActionDisplayDefinition

required

Controls how the data source appears in the Prismatic UI.

Show ActionDisplayDefinition fields

display.label

string

required

Human-readable name.

display.description

string

required

Describes what data this source provides.

display.directions

string

Additional guidance for the integration builder.

display.important

boolean

Highlights this data source as commonly used. Use sparingly.

definition.dataSourceType

DataSourceType

required

The type of UI widget used to render the data. Must be one of the values below.

Show DataSourceType values

Value	Result type	Description
`"picklist"`	`string[] \| Element[]`	A dropdown of selectable string values
`"string"`	`string`	A plain string value
`"date"`	`string`	A date string
`"timestamp"`	`string`	A datetime timestamp string
`"boolean"`	`boolean`	A boolean value
`"number"`	`number`	A numeric value
`"code"`	`string`	A code editor widget
`"schedule"`	`{ value: string }`	A schedule expression
`"objectSelection"`	`ObjectSelection`	Multi-object selector with optional field selection
`"objectFieldMap"`	`ObjectFieldMap`	Field mapping between two object schemas
`"jsonForm"`	`JSONForm`	A dynamic form driven by a JSON Schema and UI schema

definition.perform

DataSourcePerformFunction

required

The async function that fetches data and returns it in the format required by dataSourceType.

perform: (
  context: DataSourceContext<TConfigVars>,
  params: ActionInputParameters<TInputs>
) => Promise<DataSourceResult<TDataSourceType>>

Show DataSourceContext fields

context.logger

ActionLogger

Structured logger: trace, debug, info, log, warn, error, metric.

context.customer

CustomerAttributes

Attributes of the customer: id, name, externalId.

context.instance

InstanceAttributes

Attributes of the instance: id, name.

context.user

UserAttributes

Attributes of the user for User Level Configurations: id, name, email, externalId.

context.configVars

TConfigVars

Key/value collection of config variables.

DataSourceContext is a subset of ActionContext. It does not include instanceState, crossFlowState, executionState, integrationState, stepId, executionId, webhookUrls, or invokeFlow.

definition.inputs

TInputs

required

A record of input field definitions. See input.

definition.examplePayload

Awaited<ReturnType<perform>>

Example return value for UI preview.

definition.detailDataSource

string

The key of another data source in the same component that provides additional details about the content of this data source (e.g., example field values for an objectFieldMap).

Return type

The perform function must return a Promise<DataSourceResult<TDataSourceType>>:

result

DataSourceResultType

required

The data returned by the data source. The type depends on dataSourceType.

supplementalData

{ data: unknown; contentType: string }

Optional extra data available during config wizard page loading. Not passed to action steps.

Examples

picklist
objectSelection
objectFieldMap
jsonForm

import { dataSource, input } from "@prismatic-io/spectral";

export const listProjects = dataSource({
  display: {
    label: "List Projects",
    description: "Fetch available projects for selection",
  },
  dataSourceType: "picklist",
  inputs: {
    connection: input({ label: "Connection", type: "connection", required: true }),
  },
  perform: async (context, params) => {
    const apiKey = params.connection.fields.apiKey as string;
    const projects = await fetchProjects(apiKey);

    return {
      result: projects.map((p) => ({ key: p.id, label: p.name })),
    };
  },
  examplePayload: {
    result: [
      { key: "proj_1", label: "Alpha" },
      { key: "proj_2", label: "Beta" },
    ],
  },
});

async function fetchProjects(apiKey: string) {
  return [{ id: "proj_1", name: "Alpha" }, { id: "proj_2", name: "Beta" }];
}

import { dataSource, input } from "@prismatic-io/spectral";

export const selectObjects = dataSource({
  display: {
    label: "Select Objects",
    description: "Choose which objects and fields to sync",
  },
  dataSourceType: "objectSelection",
  inputs: {
    connection: input({ label: "Connection", type: "connection", required: true }),
  },
  perform: async (context, params) => {
    return {
      result: [
        {
          object: { key: "contacts", label: "Contacts" },
          fields: [
            { key: "id", label: "ID" },
            { key: "email", label: "Email" },
            { key: "name", label: "Name" },
          ],
          defaultSelected: true,
        },
      ],
    };
  },
});

import { dataSource, input } from "@prismatic-io/spectral";

export const mapFields = dataSource({
  display: {
    label: "Map Fields",
    description: "Map source fields to destination fields",
  },
  dataSourceType: "objectFieldMap",
  inputs: {
    connection: input({ label: "Connection", type: "connection", required: true }),
  },
  perform: async (context, params) => {
    return {
      result: {
        fields: [
          {
            field: { key: "firstName", label: "First Name" },
            mappedObject: { key: "contacts", label: "Contacts" },
            mappedField: { key: "first_name", label: "First Name" },
          },
        ],
        options: [
          {
            object: { key: "contacts", label: "Contacts" },
            fields: [
              { key: "first_name", label: "First Name" },
              { key: "last_name", label: "Last Name" },
            ],
          },
        ],
      },
    };
  },
});

import { dataSource, input } from "@prismatic-io/spectral";

export const configForm = dataSource({
  display: {
    label: "Configuration Form",
    description: "Dynamic form for advanced configuration",
  },
  dataSourceType: "jsonForm",
  inputs: {
    connection: input({ label: "Connection", type: "connection", required: true }),
  },
  perform: async (context, params) => {
    return {
      result: {
        schema: {
          type: "object",
          properties: {
            region: { type: "string", enum: ["us-east-1", "eu-west-1"] },
            batchSize: { type: "number", minimum: 1, maximum: 1000 },
          },
        },
        uiSchema: {
          type: "VerticalLayout",
          elements: [
            { type: "Control", scope: "#/properties/region" },
            { type: "Control", scope: "#/properties/batchSize" },
          ],
        },
        data: { region: "us-east-1", batchSize: 100 },
      },
    };
  },
});

input — Define inputs for a data source
connection — Define the connection passed to perform
component — Register data sources in a component

Core Functions

Code-Native Integration Functions

Testing Utilities

Utility Module

Function signature

Parameters

`DataSourceDefinition` fields

Return type

Examples

Build docs developers (and LLMs) love

Core Functions

Code-Native Integration Functions

Testing Utilities

Utility Module

​Function signature

​Parameters

​DataSourceDefinition fields

​Return type

​Examples

​Related

Build docs developers (and LLMs) love

Function signature

Parameters

`DataSourceDefinition` fields

Return type

Examples

Related