Skip to main content
Inputs are the configuration fields that integration builders fill in when using an action, trigger, or data source. They are defined with input() and passed to the inputs field of an action, trigger, or data source.

​
input() function

export const input = <T extends InputFieldDefinition>(definition: T): T => definition;
All inputs share a common set of base fields: 
interface BaseInputField {
  /** Display name shown in the Prismatic UI. */
  label: { key: string; value: string } | string;
  /** Placeholder text shown when the field is empty. */
  placeholder?: string;
  /** Help text displayed below the input. */
  comments?: string;
  /** Example value shown to guide the integration builder. */
  example?: string;
  /** Whether this input must be provided. */
  required?: boolean;
  /** Key of a data source whose result can populate this input. */
  dataSource?: string;
}

​
InputFieldType reference

The type field on an input determines how it is rendered in the UI and what value your perform function receives.
typeDescriptionValue in perform
"string"Single-line text inputstring
"text"Multi-line text areastring
"data"Binary or base64 datastring
"password"Masked single-line inputstring
const endpoint = input({
  label: "API Endpoint",
  type: "string",
  required: true,
  placeholder: "https://api.example.com",
  example: "https://api.acme.com/v2",
  comments: "The base URL of the API to call",
});

const payload = input({
  label: "Request Body",
  type: "text",
  comments: "JSON or XML body to send with the request",
});

const secretKey = input({
  label: "Secret Key",
  type: "password",
  required: true,
});

​
Collection inputs

Most input types support a collection field that changes the input from a single value into a list:
collectionUIValue in perform
undefined (default)Single value inputT
"valuelist"Add/remove list of valuesT[]
"keyvaluelist"Add/remove key-value pairsKeyValuePair<T>[]
const tags = input({
  label: "Tags",
  type: "string",
  collection: "valuelist",
  comments: "One tag per row",
});

const headers = input({
  label: "HTTP Headers",
  type: "string",
  collection: "keyvaluelist",
  comments: "Headers to include in the request",
});
The KeyValuePair type: 
interface KeyValuePair<V = unknown> {
  key: string;
  value: V;
}

​
The clean function

The optional clean function is called on the raw input value before it is passed to perform. Use it to coerce types, apply defaults, or validate values: 
import { input, util } from "@prismatic-io/spectral";

const pageSize = input({
  label: "Page Size",
  type: "string",
  default: "50",
  required: false,
  clean: (value) => {
    const parsed = parseInt(String(value ?? "50"), 10);
    if (isNaN(parsed) || parsed < 1) {
      throw new Error("Page size must be a positive integer");
    }
    return Math.min(parsed, 100); // cap at 100
  },
});

const enableDebug = input({
  label: "Enable Debug Logging",
  type: "boolean",
  default: "false",
  clean: util.types.toBool, // Converts string "true"/"false" to boolean
});
The clean function runs before perform is called. The cleaned value (return value of clean) is what your action receives in params.

​
model field — restricting to predefined choices

For string, data, text, password, boolean, date, and timestamp inputs, you can restrict the choices to a fixed list using model: 
const region = input({
  label: "AWS Region",
  type: "string",
  required: true,
  model: [
    { label: "US East (N. Virginia)", value: "us-east-1" },
    { label: "US West (Oregon)", value: "us-west-2" },
    { label: "EU (Ireland)", value: "eu-west-1" },
    { label: "Asia Pacific (Tokyo)", value: "ap-northeast-1" },
  ],
});

​
dataSource field — dynamic choices

Set dataSource to the key of a data source defined in the same component to populate the input’s choices dynamically at config time: 
const projectId = input({
  label: "Project",
  type: "string",
  required: true,
  dataSource: "listProjects", // Key of a dataSource in the same component
  comments: "The project to create the issue in",
});

​
onPremControlType for connection inputs

When building an onPremConnection, the host and port inputs must include onPremControlled: true. This signals that the Prismatic on-prem agent will override these values with local tunnel endpoints: 
const hostInput = {
  label: "Host",
  type: "string" as const,
  required: true,
  onPremControlled: true, // Required for on-prem connections
  comments: "Database hostname — overridden by the on-prem agent when active",
};

​
Shared inputs

Inputs can be defined once and reused across multiple actions: 
// inputs.ts
import { input } from "@prismatic-io/spectral";

export const connectionInput = input({
  label: "Connection",
  type: "connection",
  required: true,
});

export const recordIdInput = input({
  label: "Record ID",
  type: "string",
  required: true,
  placeholder: "rec_01HXYZ",
  comments: "The unique identifier of the record to operate on",
});

// actions.ts
import { action } from "@prismatic-io/spectral";
import { connectionInput, recordIdInput } from "./inputs";

export const getRecord = action({
  display: { label: "Get Record", description: "Retrieve a single record" },
  inputs: { connection: connectionInput, recordId: recordIdInput },
  perform: async (context, params) => {
    // params.connection and params.recordId are available
    return { data: null };
  },
});

Build docs developers (and LLMs) love

Get started for freeTalk to us