Skip to main content
The action function creates an action object that can be referenced by a custom component. Actions are the building blocks of integration flows — each action performs a discrete unit of work, such as making an API call, transforming data, or writing to a database.

​
Function signature

function action<
  TInputs extends Inputs,
  TConfigVars extends ConfigVarResultCollection,
  TAllowsBranching extends boolean,
  TReturn extends ActionPerformReturn<TAllowsBranching, unknown>,
>(
  definition: ActionDefinition<TInputs, TConfigVars, TAllowsBranching, TReturn>
): ActionDefinition<TInputs, TConfigVars, TAllowsBranching, TReturn>
The function validates the shape of the definition object and returns it unchanged.

​
Parameters

​
definition
ActionDefinition
required
An object describing the action. See fields below.

​
ActionDefinition fields

​
definition.display
ActionDisplayDefinition
required
Controls how the action appears in the Prismatic UI.
​
definition.perform
ActionPerformFunction
required
The async function that runs when this action is invoked. Receives context and params.
perform: async (context: ActionContext, params: ActionInputParameters<TInputs>) => Promise<TReturn>
​
definition.inputs
TInputs
required
A record of input field definitions presented to the integration builder. Values are resolved and passed to perform via params. See input.
​
definition.terminateExecution
boolean
When true, execution of the flow terminates after this action completes.
​
definition.breakLoop
boolean
When true, this action breaks out of the enclosing loop step.
​
definition.allowsBranching
boolean
When true, this action supports conditional branching. The perform function must return a result containing a branch field. See branching.
​
definition.staticBranchNames
string[]
Static list of branch names when allowsBranching is true. Use when branch names are known at design time.
​
definition.dynamicBranchInput
string
The key of the input field whose value determines branch names at runtime. Use when branches are determined dynamically.
​
definition.examplePayload
Awaited<ReturnType<perform>>
An example of the return value from perform. Used in the Prismatic UI to preview output shape.

​
Return type

The perform function must return a Promise resolving to an ActionPerformReturn:
​
data
unknown
required
The payload data returned by the action.
​
contentType
string
MIME type of the returned data (e.g., "application/json").
​
statusCode
number
HTTP status code used when this action terminates a synchronous invocation.
​
headers
Record<string, string>
HTTP headers sent back when this action terminates a synchronous invocation.
​
instanceState
Record<string, unknown>
Values to persist in the flow-specific instance state for subsequent executions.
​
crossFlowState
Record<string, unknown>
Values to persist in the cross-flow state.
​
executionState
Record<string, unknown>
Values to persist for the duration of the current execution.
​
integrationState
Record<string, unknown>
Values to persist across all flows and versions of an integration instance.
​
branch
string
Required when allowsBranching is true. The name of the branch to take.
​
failed
boolean
Set by the platform to indicate whether the action failed.
​
error
Record<string, unknown>
Set by the platform with error details when the action fails.

​
Example

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

export const listUsers = action({
  display: {
    label: "List Users",
    description: "Retrieve a paginated list of users",
    directions: "Provide a connection and optionally filter by status.",
  },
  inputs: {
    connection: input({
      label: "Connection",
      type: "connection",
      required: true,
    }),
    status: input({
      label: "Status Filter",
      type: "string",
      required: false,
      model: [
        { label: "Active", value: "active" },
        { label: "Inactive", value: "inactive" },
      ],
      comments: "Filter users by their account status.",
    }),
    maxResults: input({
      label: "Max Results",
      type: "string",
      required: false,
      default: "100",
      placeholder: "1-1000",
    }),
  },
  perform: async (context, params) => {
    const { connection, status, maxResults } = params;
    context.logger.info(`Fetching users with status: ${status}`);

    // Use connection fields to authenticate
    const apiKey = connection.fields.apiKey as string;

    const users = await fetchUsers(apiKey, { status, limit: Number(maxResults) });

    return {
      data: users,
      instanceState: { lastFetchedAt: new Date().toISOString() },
    };
  },
  examplePayload: {
    data: [{ id: "usr_123", name: "Alice", status: "active" }],
  },
});

async function fetchUsers(apiKey: string, opts: { status?: string; limit: number }) {
  // Implementation details
  return [];
}

​
Branching action example

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

export const checkStatus = action({
  display: {
    label: "Check Order Status",
    description: "Branch based on order status",
  },
  inputs: {
    orderId: input({ label: "Order ID", type: "string", required: true }),
  },
  allowsBranching: true,
  staticBranchNames: ["Pending", "Shipped", "Delivered", "Cancelled"],
  perform: async (context, params) => {
    const order = await getOrder(params.orderId);
    return {
      data: order,
      branch: order.status, // Must match one of staticBranchNames
    };
  },
});

async function getOrder(id: string) {
  return { id, status: "Shipped" };
}
  • input — Define inputs for an action
  • component — Register actions in a component
  • trigger — Define a trigger step