Component Authoring Guidelines

Integration builders use your component's labels, inputs, and output references to assemble a flow. These guidelines explain how to help them choose an action, configure it, and use its results, while keeping existing integrations working as the component evolves.

Help builders choose the right component and operation

Use a recognizable name in display.label so builders can find the component or operation they need. Use display.description to explain behavior that affects their choice, such as whether a list action returns one page or every record.

Definition	Useful details for choosing it
Component	The service or capability it provides, such as Acme ERP and the records builders can work with.
Action	The task and its result, such as List Orders and whether it returns one page or all orders.
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 builders need.
Data source	What choices it supplies, such as Select Project, and which projects it includes.

Make inputs easy to configure

Choose input types that fit the values your action expects, with labels that identify what each input controls and defaults that suit the common use case. Use comments to explain accepted formats and what happens when an optional input is left blank. A placeholder can show an example value.

For fixed choices, dropdowns save builders from looking up or typing accepted values. For choices from a connected account, data sources let customers select records directly in the embedded workflow builder. Define reusable connections so builders can supply credentials once and use them across actions.

Input values can also come from other steps and may need conversion before your action can use them. Use clean functions 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

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.

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. It also helps the embedded workflow builder's AI Copilot understand the action's results.

For fields that vary by connected account, real example data can show builders what their records contain. Inline calling lets an action fetch examples while a builder configures a step. Choose performSafety according to what the action does so these calls don't change records during configuration:

• 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. Provide known output schemas alongside inline calling so builders still have references when inputs or connections are incomplete. An examplePayload can supply specific example values. See step outputs for examples and how Prismatic selects reference data.

Choose how to fetch and process records

Choose how to fetch records based on what starts the work and how much data it may return. Account for the first run: it may need to import years of records even when subsequent runs process only a few changes.

Your use case	Where to start
Fetch records as a step in a flow	Choose an action's pagination strategy. 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 when the service provides suitable notifications. Use a polling trigger when you need to check for changes.
Split a large set of records across flow executions	Add batching to a trigger 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. For a code-native integration, see the large data sync pattern.

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 also shows how to cap records per execution and limit concurrent batches to suit the services you're calling.

Explain whether enabling a polling trigger imports historical records or starts watching for new changes. If builders can choose a starting point, explain what it controls and validate it against the source API's requirements.

Track progress across runs so a sync can continue where it left off. Test across multiple pages and failed requests to check that recovery doesn't skip records.

Help builders recover from errors

Write errors that explain what failed and what the builder should check, such as a record ID or the account's permissions. Keep credentials out of messages and logs. Report invalid credentials with a connection error so customers can identify the connection that needs attention. A shared error handler can give builders consistent explanations when several actions encounter the same API errors.

Check the builder experience before publishing

Use unit tests to check requests, returned data, and failures, including optional inputs and empty results. Compare output schemas and examples with actual results so the fields builders see match the data they receive.

Then try the component as an integration builder would. 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.

When updating a component, preserve the action keys, input keys, and output shapes that existing integrations depend on. This lets builders upgrade without reworking their flows. If a breaking change is necessary, explain what builders must change when they upgrade the component version.