Pieces

Understanding Activepieces integrations and the pieces framework

Understanding Pieces

Pieces are the building blocks of Activepieces - they’re integrations that connect your workflows to external services and APIs. With over 600 pieces available, you can integrate with nearly any service, and if one doesn’t exist, you can easily create your own using TypeScript.

What are Pieces?

A piece is a packaged integration that provides:

• Actions: Operations you can perform (send email, create record, etc.)
• Triggers: Events that start flows (new email, form submission, etc.)
• Authentication: Secure connection management
• Properties: Configurable inputs for actions and triggers

Piece Structure

Based on the Activepieces framework source code, here’s how pieces are defined:

import { createPiece, PieceAuth } from '@activepieces/pieces-framework';

export const myPiece = createPiece({
  displayName: 'My Service',
  description: 'Integration with My Service',
  auth: PieceAuth.OAuth2({
    authUrl: 'https://api.myservice.com/oauth/authorize',
    tokenUrl: 'https://api.myservice.com/oauth/token',
    required: true,
    scope: ['read', 'write']
  }),
  minimumSupportedRelease: '0.30.0',
  logoUrl: 'https://cdn.activepieces.com/pieces/myservice.png',
  authors: ['YourName'],
  categories: [PieceCategory.PRODUCTIVITY],
  actions: [
    createRecordAction,
    updateRecordAction,
    deleteRecordAction
  ],
  triggers: [
    newRecordTrigger,
    updatedRecordTrigger
  ],
});

Types of Pieces

Activepieces organizes pieces into three categories:

Core Pieces

Core pieces are essential integrations maintained by the Activepieces team. Located in packages/pieces/core/, there are 26 core pieces including:

• HTTP: Make requests to any API
• Code: Write custom JavaScript/TypeScript
• Schedule: Trigger flows on a schedule
• Webhook: Receive HTTP requests
• Data Mapper: Transform and manipulate data
• AI: AI-powered text, image, and agent operations

Core pieces are:

• Always available
• Battle-tested and reliable
• Maintained with every Activepieces release
• Include fundamental workflow operations

Community Pieces

Community pieces are integrations contributed by the open source community. Located in packages/pieces/community/, there are 597+ community pieces including:

• Google Sheets, Gmail, Google Drive
• Slack, Discord, Microsoft Teams
• OpenAI, Anthropic, Replicate
• Airtable, Notion, Asana
• Stripe, PayPal, Shopify
• And hundreds more!

Over 95% of Activepieces pieces are contributed by the community, making it one of the most contributor-friendly automation platforms.

Community pieces are:

• Open source and published to npmjs.com
• Independently versioned
• Community-maintained
• Constantly growing with new contributions

Custom Pieces

Custom pieces are private integrations you build for your specific needs. Located in packages/pieces/custom/, these pieces:

• Stay private to your instance
• Can be proprietary integrations
• Work with internal APIs
• Follow the same framework as community pieces

Piece Components

Authentication

Pieces support multiple authentication methods:

OAuth2

auth: PieceAuth.OAuth2({
  authUrl: 'https://api.service.com/oauth/authorize',
  tokenUrl: 'https://api.service.com/oauth/token',
  required: true,
  scope: ['read', 'write']
})

API Key

auth: PieceAuth.SecretText({
  displayName: 'API Key',
  description: 'Enter your API key from the service',
  required: true,
})

Basic Auth

auth: PieceAuth.BasicAuth({
  displayName: 'Credentials',
  required: true,
})

Custom Auth

auth: PieceAuth.CustomAuth({
  displayName: 'Connection',
  required: true,
  props: {
    apiKey: Property.ShortText({
      displayName: 'API Key',
      required: true,
    }),
    baseUrl: Property.ShortText({
      displayName: 'Base URL',
      required: true,
    }),
  },
})

No Auth

auth: PieceAuth.None()

Actions

Actions are operations your piece can perform. Example from the Activepieces Platform piece:

import { createAction, Property } from '@activepieces/pieces-framework';

export const createProject = createAction({
  name: 'create_project',
  displayName: 'Create Project',
  description: 'Creates a new project in Activepieces',
  auth: activePieceAuth,
  props: {
    displayName: Property.ShortText({
      displayName: 'Display Name',
      required: true,
    }),
    externalId: Property.ShortText({
      displayName: 'External ID',
      required: true,
    }),
  },
  async run(context) {
    const { displayName, externalId } = context.propsValue;
    const response = await httpClient.sendRequest({
      method: HttpMethod.POST,
      url: `${context.auth.baseApiUrl}/v1/projects`,
      headers: {
        Authorization: `Bearer ${context.auth.apiKey}`,
      },
      body: { displayName, externalId },
    });
    return response.body;
  },
});

Triggers

Triggers listen for events and start flows. They can be:

Polling Triggers

Check for new data on a schedule:

import { createTrigger, TriggerStrategy } from '@activepieces/pieces-framework';

export const newRecord = createTrigger({
  name: 'new_record',
  displayName: 'New Record',
  description: 'Triggers when a new record is created',
  type: TriggerStrategy.POLLING,
  props: {
    // Configuration properties
  },
  async onEnable(context) {
    // Setup when trigger is enabled
  },
  async onDisable(context) {
    // Cleanup when trigger is disabled
  },
  async run(context) {
    const lastCheck = context.propsValue.lastCheck;
    const newRecords = await fetchNewRecords(lastCheck);
    return newRecords;
  },
});

Webhook Triggers

Receive real-time events via webhooks:

export const newWebhook = createTrigger({
  name: 'new_webhook',
  displayName: 'New Webhook Event',
  type: TriggerStrategy.WEBHOOK,
  async onEnable(context) {
    // Register webhook with service
    await registerWebhook({
      url: context.webhookUrl,
      events: ['record.created']
    });
  },
  async onDisable(context) {
    // Unregister webhook
    await unregisterWebhook(context.webhookUrl);
  },
  async run(context) {
    return [context.payload.body];
  },
});

Properties

Properties define inputs for actions and triggers:

import { Property } from '@activepieces/pieces-framework';

// Text input
Property.ShortText({
  displayName: 'Email',
  required: true,
})

// Long text
Property.LongText({
  displayName: 'Description',
  required: false,
})

// Dropdown
Property.StaticDropdown({
  displayName: 'Priority',
  required: true,
  options: {
    options: [
      { label: 'Low', value: 'low' },
      { label: 'Medium', value: 'medium' },
      { label: 'High', value: 'high' },
    ]
  }
})

// Dynamic dropdown (fetched from API)
Property.Dropdown({
  displayName: 'Channel',
  required: true,
  refreshers: [],
  async options(context) {
    const channels = await fetchChannels(context.auth);
    return {
      options: channels.map(ch => ({
        label: ch.name,
        value: ch.id
      }))
    };
  },
})

// Number
Property.Number({
  displayName: 'Count',
  required: true,
})

// Checkbox
Property.Checkbox({
  displayName: 'Send Notification',
  required: false,
})

// Array
Property.Array({
  displayName: 'Items',
  required: true,
})

// Object/JSON
Property.Json({
  displayName: 'Configuration',
  required: false,
})

Piece Framework Features

Type Safety

The pieces framework is built with TypeScript and provides full type safety:

import { createPiece } from '@activepieces/pieces-framework';
import { PieceAuth } from '@activepieces/pieces-framework';

// TypeScript ensures correct structure
const myPiece = createPiece({
  displayName: 'My Piece',
  auth: PieceAuth.None(),
  actions: [], // Type-checked array of actions
  triggers: [], // Type-checked array of triggers
  // ... other required fields
});

NPM Package Distribution

All pieces are published as npm packages:

• Naming: @activepieces/piece-{name}
• Versioning: Follows semantic versioning
• Distribution: Published to npmjs.com
• Installation: Install like any npm package

{
  "name": "@activepieces/piece-slack",
  "version": "0.25.6",
  "dependencies": {
    "@activepieces/pieces-framework": "0.25.6",
    "@slack/web-api": "^7.9.0"
  }
}

Hot Reloading

During local development, pieces support hot reloading:

# Start dev environment with hot reloading
npm run dev

# Edit a piece file
# Changes are automatically reloaded

Context API

Pieces have access to a rich context object:

interface ActionContext {
  auth: AuthValue;           // Authentication credentials
  propsValue: PropsValue;    // Action input values
  store: Store;              // Persistent key-value store
  server: ServerContext;     // API access
  files: FilesService;       // File operations
  connections: Connections;  // Access other connections
}

MCP Server Integration

Every Activepieces piece automatically becomes available as an MCP (Model Context Protocol) server!

When you create a piece, it can be:

1. Used in Activepieces flows
2. Exposed as an MCP server tool
3. Called by AI assistants like Claude Desktop, Cursor, and Windsurf

Learn more in the MCP Servers documentation.

Building Your Own Piece

Creating a piece is straightforward:

1. Generate Piece Scaffold

   npm run create-piece
   

   Follow the prompts to set up your piece structure.

2. Define Authentication

   Choose the appropriate auth method for your service.

3. Create Actions

   Add operations users can perform.

4. Add Triggers

   Set up event listeners if needed.

5. Test Locally

   Use hot reloading to test your piece in real workflows.

6. Publish

   Publish to npm and optionally contribute back to the community.

For detailed instructions, see the Building Pieces guide.

Piece Categories

Pieces are organized into categories for easy discovery:

• Productivity: Google Workspace, Microsoft 365, Notion
• Communication: Slack, Discord, Email services
• Artificial Intelligence: OpenAI, Anthropic, AI utilities
• Marketing: Mailchimp, SendGrid, social media
• Developer Tools: GitHub, GitLab, API testing
• E-commerce: Shopify, WooCommerce, Stripe
• Business Intelligence: Analytics, reporting tools
• And many more…

Piece Versioning

Each piece specifies its minimum supported Activepieces release:

createPiece({
  minimumSupportedRelease: '0.30.0',
  maximumSupportedRelease: '0.50.0', // Optional
  // ...
})

This ensures:

• Compatibility with platform features
• Breaking changes are communicated
• Users know which version to use

Best Practices

Clear Naming

Use descriptive names for actions and triggers that clearly indicate what they do.

Good Descriptions

Write helpful descriptions for properties and include examples.

Error Handling

Handle errors gracefully and return helpful error messages.

Validation

Validate inputs before making API calls to fail fast.

Use Store

Leverage the store API for caching and state management.

Test Thoroughly

Test all actions and triggers with various inputs before publishing.

Next Steps

• Build Your First Piece - Step-by-step guide
• Piece Development Guide - Complete reference
• MCP Integration - Connect pieces to AI
• AI Pieces - Build AI-powered pieces