Add Activepieces integration for workflow automation
- Add Activepieces fork with SmoothSchedule custom piece - Create integrations app with Activepieces service layer - Add embed token endpoint for iframe integration - Create Automations page with embedded workflow builder - Add sidebar visibility fix for embed mode - Add list inactive customers endpoint to Public API - Include SmoothSchedule triggers: event created/updated/cancelled - Include SmoothSchedule actions: create/update/cancel events, list resources/services/customers 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
poduck
109
activepieces-fork/docs/build-pieces/building-pieces/create-action.mdx
Executable file
109
activepieces-fork/docs/build-pieces/building-pieces/create-action.mdx
Executable file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: 'Create Action'
|
||||
icon: 'circle-5'
|
||||
description: ''
|
||||
---
|
||||
|
||||
## Action Definition
|
||||
|
||||
Now let's create first action which fetch random ice-cream flavor.
|
||||
|
||||
```bash
|
||||
npm run cli actions create
|
||||
```
|
||||
|
||||
You will be asked three questions to define your new piece:
|
||||
|
||||
1. `Piece Folder Name`: This is the name associated with the folder where the action resides. It helps organize and categorize actions within the piece.
|
||||
2. `Action Display Name`: The name users see in the interface, conveying the action's purpose clearly.
|
||||
3. `Action Description`: A brief, informative text in the UI, guiding users about the action's function and purpose.
|
||||
Next, Let's create the action file:
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
npm run cli actions create
|
||||
|
||||
? Enter the piece folder name : gelato
|
||||
? Enter the action display name : get icecream flavor
|
||||
? Enter the action description : fetches random icecream flavor.
|
||||
```
|
||||
|
||||
This will create a new TypeScript file named `get-icecream-flavor.ts` in the `packages/pieces/community/gelato/src/lib/actions` directory.
|
||||
|
||||
Inside this file, paste the following code:
|
||||
|
||||
```typescript
|
||||
import {
|
||||
createAction,
|
||||
Property,
|
||||
PieceAuth,
|
||||
} from '@activepieces/pieces-framework';
|
||||
import { httpClient, HttpMethod } from '@activepieces/pieces-common';
|
||||
import { gelatoAuth } from '../..';
|
||||
|
||||
export const getIcecreamFlavor = createAction({
|
||||
name: 'get_icecream_flavor', // Must be a unique across the piece, this shouldn't be changed.
|
||||
auth: gelatoAuth,
|
||||
displayName: 'Get Icecream Flavor',
|
||||
description: 'Fetches random icecream flavor',
|
||||
props: {},
|
||||
async run(context) {
|
||||
const res = await httpClient.sendRequest<string[]>({
|
||||
method: HttpMethod.GET,
|
||||
url: 'https://cloud.activepieces.com/api/v1/webhooks/RGjv57ex3RAHOgs0YK6Ja/sync',
|
||||
headers: {
|
||||
Authorization: context.auth, // Pass API key in headers
|
||||
},
|
||||
});
|
||||
return res.body;
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
The createAction function takes an object with several properties, including the `name`, `displayName`, `description`, `props`, and `run` function of the action.
|
||||
|
||||
The `name` property is a unique identifier for the action. The `displayName` and `description` properties are used to provide a human-readable name and description for the action.
|
||||
|
||||
The `props` property is an object that defines the properties that the action requires from the user. In this case, the action doesn't require any properties.
|
||||
|
||||
The `run` function is the function that is called when the action is executed. It takes a single argument, context, which contains the values of the action's properties.
|
||||
|
||||
The `run` function utilizes the httpClient.sendRequest function to make a GET request, fetching a random ice cream flavor. It incorporates API key authentication in the request headers. Finally, it returns the response body.
|
||||
|
||||
## Expose The Definition
|
||||
|
||||
To make the action readable by Activepieces, add it to the array of actions in the piece definition.
|
||||
|
||||
```typescript
|
||||
import { createPiece } from '@activepieces/pieces-framework';
|
||||
// Don't forget to add the following import.
|
||||
import { getIcecreamFlavor } from './lib/actions/get-icecream-flavor';
|
||||
|
||||
export const gelato = createPiece({
|
||||
displayName: 'Gelato',
|
||||
logoUrl: 'https://cdn.activepieces.com/pieces/gelato.png',
|
||||
authors: [],
|
||||
auth: gelatoAuth,
|
||||
// Add the action here.
|
||||
actions: [getIcecreamFlavor], // <--------
|
||||
triggers: [],
|
||||
});
|
||||
```
|
||||
|
||||
# Testing
|
||||
|
||||
By default, the development setup only builds specific components. Open the file `packages/server/api/.env` and include "gelato" in the `AP_DEV_PIECES`.
|
||||
|
||||
For more details, check out the [Piece Development](./development-setup) section.
|
||||
|
||||
Once you edit the environment variable, restart the backend. The piece will be rebuilt. After this process, you'll need to **refresh** the frontend to see the changes.
|
||||
|
||||
<Tip>
|
||||
If the build fails, try debugging by running `npx nx run-many -t build --projects=gelato`.
|
||||
It will display any errors in your code.
|
||||
</Tip>
|
||||
|
||||
To test the action, use the flow builder in Activepieces. It should function as shown in the screenshot.
|
||||
|
||||
|
||||
@@ -0,0 +1,137 @@
|
||||
---
|
||||
title: 'Create Trigger'
|
||||
icon: 'circle-6'
|
||||
description: ''
|
||||
---
|
||||
|
||||
This tutorial will guide you through the process of creating trigger for a Gelato piece that fetches new icecream flavor.
|
||||
|
||||
## Trigger Definition
|
||||
|
||||
To create trigger run the following command,
|
||||
|
||||
```bash
|
||||
npm run cli triggers create
|
||||
```
|
||||
|
||||
1. `Piece Folder Name`: This is the name associated with the folder where the trigger resides. It helps organize and categorize triggers within the piece.
|
||||
2. `Trigger Display Name`: The name users see in the interface, conveying the trigger's purpose clearly.
|
||||
3. `Trigger Description`: A brief, informative text in the UI, guiding users about the trigger's function and purpose.
|
||||
4. `Trigger Technique`: Specifies the trigger type - either [polling](../piece-reference/triggers/polling-trigger) or [webhook](../piece-reference/triggers/webhook-trigger).
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
npm run cli triggers create
|
||||
|
||||
? Enter the piece folder name : gelato
|
||||
? Enter the trigger display name : new flavor created
|
||||
? Enter the trigger description : triggers when a new icecream flavor is created.
|
||||
? Select the trigger technique: polling
|
||||
```
|
||||
|
||||
This will create a new TypeScript file at `packages/pieces/community/gelato/src/lib/triggers` named `new-flavor-created.ts`.
|
||||
|
||||
Inside this file, paste the following code:
|
||||
|
||||
```ts
|
||||
import { gelatoAuth } from '../../';
|
||||
import {
|
||||
DedupeStrategy,
|
||||
HttpMethod,
|
||||
HttpRequest,
|
||||
Polling,
|
||||
httpClient,
|
||||
pollingHelper,
|
||||
} from '@activepieces/pieces-common';
|
||||
import {
|
||||
PiecePropValueSchema,
|
||||
TriggerStrategy,
|
||||
createTrigger,
|
||||
} from '@activepieces/pieces-framework';
|
||||
import dayjs from 'dayjs';
|
||||
|
||||
const polling: Polling<
|
||||
PiecePropValueSchema<typeof gelatoAuth>,
|
||||
Record<string, never>
|
||||
> = {
|
||||
strategy: DedupeStrategy.TIMEBASED,
|
||||
items: async ({ auth, propsValue, lastFetchEpochMS }) => {
|
||||
const request: HttpRequest = {
|
||||
method: HttpMethod.GET,
|
||||
url: 'https://cloud.activepieces.com/api/v1/webhooks/aHlEaNLc6vcF1nY2XJ2ed/sync',
|
||||
headers: {
|
||||
authorization: auth,
|
||||
},
|
||||
};
|
||||
const res = await httpClient.sendRequest(request);
|
||||
return res.body['flavors'].map((flavor: string) => ({
|
||||
epochMilliSeconds: dayjs().valueOf(),
|
||||
data: flavor,
|
||||
}));
|
||||
},
|
||||
};
|
||||
|
||||
export const newFlavorCreated = createTrigger({
|
||||
auth: gelatoAuth,
|
||||
name: 'newFlavorCreated',
|
||||
displayName: 'new flavor created',
|
||||
description: 'triggers when a new icecream flavor is created.',
|
||||
props: {},
|
||||
sampleData: {},
|
||||
type: TriggerStrategy.POLLING,
|
||||
async test(context) {
|
||||
return await pollingHelper.test(polling, context);
|
||||
},
|
||||
async onEnable(context) {
|
||||
const { store, auth, propsValue } = context;
|
||||
await pollingHelper.onEnable(polling, { store, auth, propsValue });
|
||||
},
|
||||
|
||||
async onDisable(context) {
|
||||
const { store, auth, propsValue } = context;
|
||||
await pollingHelper.onDisable(polling, { store, auth, propsValue });
|
||||
},
|
||||
|
||||
async run(context) {
|
||||
return await pollingHelper.poll(polling, context);
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
The way polling triggers usually work is as follows:
|
||||
|
||||
`Run`:The run method executes every 5 minutes, fetching data from the endpoint within a specified timestamp range or continuing until it identifies the last item ID. It then returns the new items as an array. In this example, the httpClient.sendRequest method is utilized to retrieve new flavors, which are subsequently stored in the store along with a timestamp.
|
||||
|
||||
## Expose The Definition
|
||||
|
||||
To make the trigger readable by Activepieces, add it to the array of triggers in the piece definition.
|
||||
|
||||
```typescript
|
||||
import { createPiece } from '@activepieces/pieces-framework';
|
||||
import { getIcecreamFlavor } from './lib/actions/get-icecream-flavor';
|
||||
// Don't forget to add the following import.
|
||||
import { newFlavorCreated } from './lib/triggers/new-flavor-created';
|
||||
|
||||
export const gelato = createPiece({
|
||||
displayName: 'Gelato Tutorial',
|
||||
logoUrl: 'https://cdn.activepieces.com/pieces/gelato.png',
|
||||
authors: [],
|
||||
auth: gelatoAuth,
|
||||
actions: [getIcecreamFlavor],
|
||||
// Add the trigger here.
|
||||
triggers: [newFlavorCreated], // <--------
|
||||
});
|
||||
```
|
||||
|
||||
# Testing
|
||||
|
||||
By default, the development setup only builds specific components. Open the file `packages/server/api/.env` and include "gelato" in the `AP_DEV_PIECES`.
|
||||
|
||||
For more details, check out the [Piece Development](./development-setup) section.
|
||||
|
||||
Once you edit the environment variable, restart the backend. The piece will be rebuilt. After this process, you'll need to **refresh** the frontend to see the changes.
|
||||
|
||||
To test the trigger, use the load sample data from flow builder in Activepieces. It should function as shown in the screenshot.
|
||||
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: 'Development setup'
|
||||
icon: 'circle-2'
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js v18+
|
||||
- npm v9+
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Setup the environment
|
||||
|
||||
```bash
|
||||
node tools/setup-dev.js
|
||||
```
|
||||
|
||||
2. Start the environment
|
||||
|
||||
This command will start activepieces with sqlite3 and in memory queue.
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
<Note>
|
||||
By default, the development setup only builds specific pieces.Open the file
|
||||
`packages/server/api/.env` and add comma-separated list of pieces to make
|
||||
available.
|
||||
|
||||
For more details, check out the [Piece Development](/build-pieces/building-pieces/development-setup#pieces-development) section.
|
||||
|
||||
</Note>
|
||||
|
||||
3. Go to **_localhost:4200_** on your web browser and sign in with these details:
|
||||
|
||||
Email: `dev@ap.com`
|
||||
Password: `12345678`
|
||||
|
||||
|
||||
## Pieces Development
|
||||
|
||||
When [`AP_SYNC_MODE`](https://github.com/activepieces/activepieces/blob/main/packages/server/api/.env#L17) is set to `OFFICIAL_AUTO`, all pieces are automatically loaded from the cloud API and synced to the database on first launch. This process may take a few seconds to several minutes depending on your internet connection.
|
||||
|
||||
For local development, pieces are loaded from your local `dist` folder instead of the database. To enable this, set the [`AP_DEV_PIECES`](https://github.com/activepieces/activepieces/blob/main/packages/server/api/.env#L4) environment variable with a comma-separated list of pieces. For example, to develop with `google-sheets` and `cal-com`:
|
||||
|
||||
```sh
|
||||
AP_DEV_PIECES=google-sheets,cal-com npm start
|
||||
```
|
||||
31
activepieces-fork/docs/build-pieces/building-pieces/overview.mdx
Executable file
31
activepieces-fork/docs/build-pieces/building-pieces/overview.mdx
Executable file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: 'Overview'
|
||||
description: 'This section helps developers build and contribute pieces.'
|
||||
icon: 'hand-wave'
|
||||
---
|
||||
|
||||
Building pieces is fun and important; it allows you to customize Activepieces for your own needs.
|
||||
|
||||
<Tip>
|
||||
We love contributions! In fact, most of the pieces are contributed by the community. Feel free to open a pull request.
|
||||
</Tip>
|
||||
<Tip>
|
||||
**Friendly Tip:**
|
||||
For the fastest support, we recommend joining our Discord community. We are dedicated to addressing every question and concern raised there.
|
||||
</Tip>
|
||||
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Code with TypeScript" icon="code">
|
||||
Build pieces using TypeScript for a more powerful and flexible development process.
|
||||
</Card>
|
||||
<Card title="Hot Reloading" icon="cloud-bolt">
|
||||
See your changes in the browser within 7 seconds.
|
||||
</Card>
|
||||
<Card title="Open Source" icon="earth-americas">
|
||||
Work within the open-source environment, explore, and contribute to other pieces.
|
||||
</Card>
|
||||
<Card title="Community Support" icon="people">
|
||||
Join our large community, where you can ask questions, share ideas, and develop alongside others.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: 'Add Piece Authentication'
|
||||
icon: 'circle-4'
|
||||
description: ''
|
||||
---
|
||||
|
||||
|
||||
### Piece Authentication
|
||||
|
||||
Activepieces supports multiple forms of authentication, you can check those forms [here](../piece-reference/authentication)
|
||||
|
||||
Now, let's establish authentication for this piece, which necessitates the inclusion of an API Key in the headers.
|
||||
|
||||
Modify `src/index.ts` file to add authentication,
|
||||
|
||||
```ts
|
||||
import { PieceAuth, createPiece } from '@activepieces/pieces-framework';
|
||||
|
||||
export const gelatoAuth = PieceAuth.SecretText({
|
||||
displayName: 'API Key',
|
||||
required: true,
|
||||
description: 'Please use **test-key** as value for API Key',
|
||||
});
|
||||
|
||||
export const gelato = createPiece({
|
||||
displayName: 'Gelato',
|
||||
logoUrl: 'https://cdn.activepieces.com/pieces/gelato.png',
|
||||
auth: gelatoAuth,
|
||||
authors: [],
|
||||
actions: [],
|
||||
triggers: [],
|
||||
});
|
||||
```
|
||||
|
||||
<Note>
|
||||
Use the value **test-key** as the API key when testing actions or triggers for
|
||||
Gelato.
|
||||
</Note>
|
||||
51
activepieces-fork/docs/build-pieces/building-pieces/piece-definition.mdx
Executable file
51
activepieces-fork/docs/build-pieces/building-pieces/piece-definition.mdx
Executable file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: 'Create Piece Definition'
|
||||
icon: 'circle-3'
|
||||
description: ''
|
||||
---
|
||||
|
||||
|
||||
This tutorial will guide you through the process of creating a Gelato piece with an action that fetches random icecream flavor and trigger that fetches new icecream flavor created. It assumes that you are familiar with the following:
|
||||
|
||||
- [Activepieces Local development](./development-setup) Or [GitHub Codespaces](../misc/codespaces).
|
||||
- TypeScript syntax.
|
||||
|
||||
## Piece Definition
|
||||
|
||||
To get started, let's generate a new piece for Gelato
|
||||
|
||||
```bash
|
||||
npm run cli pieces create
|
||||
```
|
||||
|
||||
You will be asked three questions to define your new piece:
|
||||
|
||||
1. `Piece Name`: Specify a name for your piece. This name uniquely identifies your piece within the ActivePieces ecosystem.
|
||||
2. `Package Name`: Optionally, you can enter a name for the npm package associated with your piece. If left blank, the default name will be used.
|
||||
3. `Piece Type`: Choose the piece type based on your intention. It can be either "custom" if it's a tailored solution for your needs, or "community" if it's designed to be shared and used by the broader community.
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
npm run cli pieces create
|
||||
|
||||
? Enter the piece name: gelato
|
||||
? Enter the package name: @activepieces/piece-gelato
|
||||
? Select the piece type: community
|
||||
```
|
||||
|
||||
The piece will be generated at `packages/pieces/community/gelato/`,
|
||||
the `src/index.ts` file should contain the following code
|
||||
|
||||
```ts
|
||||
import { PieceAuth, createPiece } from '@activepieces/pieces-framework';
|
||||
|
||||
export const gelato = createPiece({
|
||||
displayName: 'Gelato',
|
||||
logoUrl: 'https://cdn.activepieces.com/pieces/gelato.png',
|
||||
auth: PieceAuth.None(),
|
||||
authors: [],
|
||||
actions: [],
|
||||
triggers: [],
|
||||
});
|
||||
```
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: 'Fork Repository'
|
||||
icon: "circle-1"
|
||||
---
|
||||
|
||||
To start building pieces, we need to fork the repository that contains the framework library and the development environment. Later, we will publish these pieces as `npm` artifacts.
|
||||
|
||||
Follow these steps to fork the repository:
|
||||
|
||||
1. Go to the repository page at https://github.com/activepieces/activepieces.
|
||||
2. Click the `Fork` button located in the top right corner of the page.
|
||||
|
||||
|
||||
|
||||
|
||||
<Tip>
|
||||
If you are an enterprise customer and want to use the private pieces feature, you can refer to the tutorial on how to set up a [private fork](../misc/private-fork).
|
||||
</Tip>
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: 'Start Building'
|
||||
icon: 'hammer'
|
||||
description: ''
|
||||
---
|
||||
This section guides you in creating a Gelato piece, from setting up your development environment to contributing the piece. By the end of this tutorial, you will have a piece with an action that fetches a random ice cream flavor and a trigger that fetches newly created ice cream flavors.
|
||||
|
||||
<Info>
|
||||
These are the next sections. In each step, we will do one small thing. This tutorial should take around 30 minutes.
|
||||
</Info>
|
||||
|
||||
## Steps Overview
|
||||
|
||||
<Steps>
|
||||
<Step title="Fork Repository" icon="code-branch">
|
||||
Fork the repository to create your own copy of the codebase.
|
||||
</Step>
|
||||
<Step title="Setup Development Environment" icon="code">
|
||||
Set up your development environment with the necessary tools and dependencies.
|
||||
</Step>
|
||||
<Step title="Create Piece Definition" icon="gear">
|
||||
Define the structure and behavior of your Gelato piece.
|
||||
</Step>
|
||||
<Step title="Add Piece Authentication" icon="lock">
|
||||
Implement authentication mechanisms for your Gelato piece.
|
||||
</Step>
|
||||
<Step title="Create Action" icon="ice-cream">
|
||||
Create an action that fetches a random ice cream flavor.
|
||||
</Step>
|
||||
<Step title="Create Trigger" icon="ice-cream">
|
||||
Create a trigger that fetches newly created ice cream flavors.
|
||||
</Step>
|
||||
<Step title="Sharing Pieces" icon="share">
|
||||
Share your Gelato piece with others.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
|
||||
<Card title="Contribution" icon="gift" iconType="duotone" color="#6e41e2">
|
||||
Contribute a piece to our repo and receive +1,400 tasks/month on [Activepieces Cloud](https://cloud.activepieces.com).
|
||||
</Card>
|
||||
Reference in New Issue
Block a user