Pieces & Integrations

How Activepieces talks to external services: the packaged integrations (pieces) and the stored credentials that authenticate them.

Language

Piece: A packaged integration (npm package) that provides triggers and actions for a specific service or capability. Avoid: connector, plugin, integration, app

Piece Metadata: The registry entry for an installed piece — name, version, auth schema, available actions/triggers.

App Connection: A stored set of credentials (OAuth2, API key, basic auth, etc.) used by pieces to authenticate with external services. Avoid: credential, auth, integration key

Connection Type: The authentication strategy for a connection: OAUTH2, CLOUD_OAUTH2, PLATFORM_OAUTH2, SECRET_TEXT, BASIC_AUTH, CUSTOM_AUTH, NO_AUTH. Avoid: auth type

Global Connection: A platform-scoped App Connection shared across all projects (scope = PLATFORM). Avoid: shared connection

OAuth App: Custom OAuth2 client credentials registered per piece to override Activepieces defaults.

externalId: A stable UUID used to cross-reference flows or connections across imports, templates, and environments.

Piece Set: A named, reusable visibility configuration (an include/exclude selection of pieces plus per-piece action/trigger allow-lists) that a platform admin assigns to many projects. Gated by platform.plan.managePiecesEnabled. Avoid: piece filter, allowed pieces list

Default Set: The single per-platform Piece Set (isDefault: true, externalId: 'default') that projects without an explicit assignment resolve to. Cannot be deleted; projects cannot be removed from it (they reassign to it).

Piece Selection: The piece-level rule inside a Piece Set: a mode (include_all = everything incl. future minus exceptions; exclude_all = only the exceptions) and an exceptions list. include_all is the "auto-include new pieces" policy. Avoid: disabledPieces, includeNewPieces, curatedPieces (all retired)

Component: An action or a trigger belonging to a piece — the umbrella term when a distinction between the two doesn't matter. Carried in code as componentType: 'action' | 'trigger' plus a componentName. Used by the MCP flow-building tools (lookupPieceComponent, validatePieceComponent, diagnosePieceProps) and the piece action/trigger visibility feature (isComponentVisible, ComponentIntent). Avoid: step, node, capability

Selected components: A per-piece allow-list of visible actions/triggers (selectedActions/selectedTriggers). A piece with an entry is "curated" — only listed components are visible and new ones stay hidden; a piece with no entry shows all components including future ones. Avoid: disabledActions, disabledTriggers

Visibility Policy: The resolved, pure value (VisibilityPolicy, from resolveVisibility({ platformId, projectId })) that answers every piece/component visibility question for a project — filterPieces, filterComponents, filterPieceComponents, isPieceVisible. Resolved once per read inside pieceMetadataService.list/get and the piece detail controller, so HTTP and MCP paths enforce identically. null for Community edition or when no project is in scope (both mean "no filtering"). managePiecesEnabled gates managing Piece Sets, never this resolution. Avoid: filterContext, enterpriseFilteringUtils (both retired)