# Component Authoring Guidelines

Design your components to help integration builders choose actions, configure inputs, and map data between steps. Clear inputs, output schemas, and useful reference data improve this design-time experience.

## Help builders choose the right component and operation[​](#help-builders-choose-the-right-component-and-operation "Direct link to Help builders choose the right component and operation")

Builders use names and descriptions to decide which component or operation fits their task. Recognizable names in `display.label` help them find it; a short `display.description` can explain the behavior that makes it the right choice.

| Definition  | Useful details for choosing it                                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Component   | The service or capability it provides, such as **Acme ERP** and the records you can work with.                                                               |
| Action      | The task and its result, such as **List Orders** and whether it returns [one page or all orders](https://prismatic.io/docs/custom-connectors/pagination.md). |
| Trigger     | What starts the integration, such as **New Order**, and whether it receives notifications or checks for changes.                                             |
| Connection  | How to connect, such as **Acme API Key**, and which credentials or permissions you need.                                                                     |
| Data source | What choices it supplies, such as **Select Project**, and which projects it includes.                                                                        |

## Make inputs easy to configure[​](#make-inputs-easy-to-configure "Direct link to Make inputs easy to configure")

Builders can configure an action more confidently when they understand what each input controls and what happens if they leave it blank. Choose [input types](https://prismatic.io/docs/custom-connectors/inputs.md) that fit the values you expect, with labels that identify their purpose and defaults that suit the common use case. A succinct `comments` explanation can clarify an accepted format or the effect of an optional value; a placeholder can show an example.

For fixed choices, dropdowns save builders from looking up or typing accepted values. For choices from a connected account, [data sources](https://prismatic.io/docs/custom-connectors/data-sources-in-embedded-workflow-builder.md) let customers select records directly in the embedded workflow builder. Reusable [connections](https://prismatic.io/docs/custom-connectors/connections.md) let builders supply credentials once and use them across actions.

Values can also come from other steps, so help text alone doesn't establish what your action receives. Use [clean functions](https://prismatic.io/docs/custom-connectors/inputs.md#cleaning-inputs) to convert those values to the expected types and formats. For values you can't accept, throw an error that names the input and explains how to correct it. When several actions use the same input, consider sharing its definition so builders encounter consistent help text, defaults, and behavior.

## Make outputs easy to understand and use[​](#make-outputs-easy-to-understand-and-use "Direct link to Make outputs easy to understand and use")

Builders need to understand an action's results to map the right data into later steps. Output schemas and example data let them explore fields and values without having to run the integration first. Actions can provide examples while builders configure a step through [inline calling](https://prismatic.io/docs/custom-connectors/step-outputs.md#safely-running-the-perform-function).

When you know the structure of the data your action returns, describe it with an `outputSchema`. Include the fields inside `data`, their nested fields, and which fields are optional. The schema gives builders output references even before they configure the action's inputs or connection, and helps the embedded workflow builder's AI Copilot understand its results. Real example data can also reveal fields that vary by connected account.

To provide those examples without changing records while a builder configures a step, choose `performSafety` according to what the action does:

* Set it to `"safe"` when `perform` can run outside a workflow execution without changing data or causing other unwanted effects. Fetching a record or formatting a string are typical examples.
* Set it to `"notAllowed"` for actions that create, update, or delete data, or otherwise shouldn't run while a builder configures a step. If fetching an existing record can provide a useful example, use `examplePerform` to supply it without changing data.

Inline calls run independently of a workflow, so they need to work with the supplied inputs rather than state stored during a workflow run. Keep known output schemas alongside inline calling to provide references while inputs or connections are incomplete. An `examplePayload` can supply specific example values. See [step outputs](https://prismatic.io/docs/custom-connectors/step-outputs.md) for examples and how Prismatic selects reference data.

## Choose how to fetch and process records[​](#choose-how-to-fetch-and-process-records "Direct link to Choose how to fetch and process records")

A first run may need to import years of records even when subsequent runs only process a few changes.

| Your use case                                             | Where to start                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fetch records as a step in a flow                         | Choose an action's [pagination strategy](https://prismatic.io/docs/custom-connectors/pagination.md). Fetching all pages can suit small datasets with a known size limit; let builders request one page at a time when results may be large.                                                                   |
| React to changes in another service                       | Use a [webhook trigger](https://prismatic.io/docs/custom-connectors/triggers.md#app-event-webhook-triggers) when the service provides suitable notifications. Use a [polling trigger](https://prismatic.io/docs/custom-connectors/triggers.md#app-event-polling-triggers) when you need to check for changes. |
| Split a large set of records across flow executions       | Add [batching to a trigger](https://prismatic.io/docs/custom-connectors/triggers.md#large-data-syncs) so the flow processes smaller groups of records. This includes polling triggers.                                                                                                                        |
| Import historical records when an integration is deployed | See [running batching on deploy](https://prismatic.io/docs/custom-connectors/triggers.md#running-batching-on-deploy). For a code-native integration, see the [large data sync pattern](https://prismatic.io/docs/integrations/common-patterns/large-data-sync.md).                                            |

For large syncs, prefer batching with trigger pagination over fetching all records in one trigger invocation. Your trigger fetches one page and returns a cursor so Prismatic can request the next page, while the flow processes records in smaller batches. This limits both the data held by each trigger invocation and the work handled by each batch execution. The [large data sync example](https://prismatic.io/docs/custom-connectors/triggers.md#example-large-data-sync-trigger) also shows how to cap records per execution and limit concurrent batches to suit the services you're calling.

Builders need to know whether enabling a poll will import historical records or start watching for new changes. If they can choose a starting point, explain what it controls and validate it against the source API's requirements. Tracking progress across runs lets a sync continue where it left off; tests across multiple pages and failed requests help check that recovery doesn't skip records.

## Help builders recover from errors[​](#help-builders-recover-from-errors "Direct link to Help builders recover from errors")

An error is more useful when it helps the builder decide what to do next. Explain what failed and what to check, such as a record ID or the account's permissions, while keeping credentials out of messages and logs. Report invalid credentials with a [connection error](https://prismatic.io/docs/custom-connectors/connections.md#throwing-connection-errors) so customers can identify the connection that needs attention. A shared [error handler](https://prismatic.io/docs/custom-connectors/error-handling.md) can give builders consistent explanations when several actions encounter the same API errors.

## Check the builder experience before publishing[​](#check-the-builder-experience-before-publishing "Direct link to Check the builder experience before publishing")

Tests check that an action behaves as intended; trying it in the builder also shows whether its inputs and outputs are easy to use. Use [unit tests](https://prismatic.io/docs/custom-connectors/unit-testing.md) for requests, returned data, and failures, including optional inputs and empty results. Checking schemas and examples against actual outputs helps ensure builders can rely on the fields they see. In the integration designer or embedded workflow builder you're targeting, configure an action and reference its output from another step, both before and after connecting an account. Verify that obtaining example data doesn't create, update, or delete records.

Existing integrations refer to action and input keys and depend on output shapes. Preserving these when you update a component lets builders upgrade without reworking their flows. If a breaking change is necessary, explain what builders must change when they [upgrade the component version](https://prismatic.io/docs/custom-connectors/publishing.md#component-versioning).