integration()

Creates a code-native integration object that can be imported into Prismatic.

The integration() function defines a complete code-native integration, including its flows, config pages, component registry, and metadata. It returns a converted integration object in the shape the Prismatic API expects.

Function signature

export const integration = <
  TInputs extends Inputs,
  TActionInputs extends Inputs,
  TPayload extends TriggerPayload = TriggerPayload,
  TAllowsBranching extends boolean = boolean,
  TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>,
  T extends IntegrationDefinition<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult>
    = IntegrationDefinition<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult>,
>(
  definition: T,
): ReturnType<typeof convertIntegration<...>>

When the environment variable DEBUG is set to "true", the function prints the generated YAML representation of the integration to the console via console.info.

Parameters

definition · IntegrationDefinition · required

An object that describes the integration. See the fields below.

Show IntegrationDefinition fields

name · string · required

The unique name for this integration.

description · string

Human-readable description for this integration.

iconPath · string

Path to the icon image to use for this integration. The path should be relative to the built integration source.

category · string

Category for this integration, used for organization in the Prismatic UI.

documentation · string

Documentation URL or content for this integration.

version · string

Version identifier for this integration.

labels · string[]

Labels for this integration.

endpointType · EndpointType · default: "flow_specific"

Endpoint type used by instances of this integration. When using anything other than flow_specific, a preprocess flow config must be specified.

Accepted values:

• "flow_specific" — Each flow has its own unique endpoint URL.
• "instance_specific" — All flows in an instance share one endpoint URL.
• "shared_instance" — All instances share a single endpoint URL.

triggerPreprocessFlowConfig · PreprocessFlowConfig

Preprocess flow configuration for when the trigger payload contains the flow routing attributes. Cannot be specified together with a preprocess flow on a flow.

Show PreprocessFlowConfig fields

flowNameField · string · required

Name of the field in the trigger payload used to determine which flow to execute.

externalCustomerIdField · string

Name of the field in the payload used as the external customer ID.

externalCustomerUserIdField · string

Name of the field in the payload used as the external customer user ID.

flows · Flow[] · required

Array of flows for this integration. Each flow defines a trigger and execution logic. See flow().

configPages · ConfigPages

Config wizard pages shown to customers when deploying an instance of this integration. See configPage().

userLevelConfigPages · UserLevelConfigPages

Config wizard pages for user-level configuration. These pages appear in the user-level config wizard instead of the instance-level wizard.

scopedConfigVars · ScopedConfigVarMap

Scoped config variables for this integration. Supports OrganizationActivatedConnectionConfigVar entries.

instanceProfile · string

Instance profile to use for this integration. If not specified, the tenant’s default instance profile is used.

componentRegistry · ComponentRegistry

A registry of components this integration depends on. Used to make component actions available in context.components during flow execution. See componentManifest().

Return type

integration · object

A converted integration object in the shape the Prismatic API expects, including a codeNativeIntegrationYAML property.

Example

import {
  integration,
  flow,
  configPage,
  configVar,
  connectionConfigVar,
} from "@prismatic-io/spectral";

export default integration({
  name: "My Integration",
  description: "Syncs data between two services.",
  iconPath: "icon.png",
  category: "Data Sync",
  version: "1.0.0",
  labels: ["sync", "data"],
  endpointType: "flow_specific",
  flows: [
    flow({
      name: "Sync Data",
      stableKey: "sync-data",
      onExecution: async (context, params) => {
        const { logger } = context;
        logger.info("Running sync...");
        return { data: null };
      },
    }),
  ],
  configPages: {
    "Connection Setup": configPage({
      tagline: "Connect your accounts",
      elements: {
        "My Connection": connectionConfigVar({
          stableKey: "my-connection",
          dataType: "connection",
          inputs: {},
        }),
      },
    }),
  },
});

Related

• flow() — Define individual flows within an integration.
• configPage() — Define config wizard pages.
• configVar() — Define standard config variables.
• connectionConfigVar() — Define connection config variables.
• componentManifest() — Register components used by the integration.